From 03a2a3a6773785e087b296e9e6ff6791c6068f60 Mon Sep 17 00:00:00 2001 From: Jan Janssen Date: Fri, 11 Aug 2023 12:26:27 +0200 Subject: [PATCH] docs: Add more feature truth tables These are much easier to understand at a glance than free-form text. --- docs/yaml/objects/feature.yaml | 38 +++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/docs/yaml/objects/feature.yaml b/docs/yaml/objects/feature.yaml index 3e37644f4..26b677f7a 100644 --- a/docs/yaml/objects/feature.yaml +++ b/docs/yaml/objects/feature.yaml @@ -27,11 +27,11 @@ methods: description: | Returns the feature, with `'auto'` converted to `'disabled'` if value is true. - | Feature / Condition | `value = true` | `value = false` | - | ------------------- | -------------- | --------------- | - | Enabled | Enabled | Enabled | - | Disabled | Disabled | Disabled | - | Auto | Disabled | Auto | + | Feature | `value = true` | `value = false` | + | -------- | -------------- | --------------- | + | Auto | Disabled | Auto | + | Enabled | Enabled | Enabled | + | Disabled | Disabled | Disabled | posargs: value: @@ -44,11 +44,11 @@ methods: description: | Returns the feature, with `'auto'` converted to `'enabled'` if value is true. - | Feature / Condition | `value = true` | `value = false` | - | ------------------- | -------------- | --------------- | - | Enabled | Enabled | Enabled | - | Disabled | Disabled | Disabled | - | Auto | Enabled | Auto | + | Feature | `value = true` | `value = false` | + | -------- | -------------- | --------------- | + | Auto | Enabled | Auto | + | Enabled | Enabled | Enabled | + | Disabled | Disabled | Disabled | posargs: value: @@ -63,6 +63,12 @@ methods: `'enabled'` and the value is false; a disabled feature if the object is `'auto'` or `'disabled'` and the value is false. + | Feature | `value = true` | `value = false` | + | -------- | -------------- | --------------- | + | Auto | Auto | Disabled | + | Enabled | Enabled | Error | + | Disabled | Disabled | Disabled | + example: | `require` is useful to restrict the applicability of `'auto'` features, for example based on other features or on properties of the host machine: @@ -94,6 +100,12 @@ methods: `'disabled'` and the value is true; an enabled feature if the object is `'auto'` or `'enabled'` and the value is true. + | Feature | `value = true` | `value = false` | + | -------- | -------------- | --------------- | + | Auto | Enabled | Auto | + | Enabled | Enabled | Enabled | + | Disabled | Error | Disabled | + example: | `enable_if` is useful to restrict the applicability of `'auto'` features, particularly when passing them to [[dependency]]: @@ -122,6 +134,12 @@ methods: `'enabled'` and the value is true; a disabled feature if the object is `'auto'` or `'disabled'` and the value is true. + | Feature | `value = true` | `value = false` | + | -------- | -------------- | --------------- | + | Auto | Disabled | Auto | + | Enabled | Error | Enabled | + | Disabled | Disabled | Disabled | + This is equivalent to `feature_opt.require(not condition)`, but may make code easier to reason about, especially when mixed with `enable_if`