docs: Add more feature truth tables

These are much easier to understand at a glance than free-form text.
pull/12121/head
Jan Janssen 1 year ago committed by Xavier Claessens
parent 32e7ebc821
commit 03a2a3a677
  1. 30
      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` |
| ------------------- | -------------- | --------------- |
| Feature | `value = true` | `value = false` |
| -------- | -------------- | --------------- |
| Auto | Disabled | Auto |
| Enabled | Enabled | Enabled |
| Disabled | Disabled | Disabled |
| Auto | Disabled | Auto |
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` |
| ------------------- | -------------- | --------------- |
| Feature | `value = true` | `value = false` |
| -------- | -------------- | --------------- |
| Auto | Enabled | Auto |
| Enabled | Enabled | Enabled |
| Disabled | Disabled | Disabled |
| Auto | Enabled | Auto |
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`

Loading…
Cancel
Save