docs: Improve visibility for `.enabled()` etc., add example [skip ci]

2 files changed, 32 insertions, 5 deletions

diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md
index 8b29afd..2d53e28 100644
--- a/docs/markdown/Build-options.md
+++ b/docs/markdown/Build-options.md
@@ -83,9 +83,9 @@ Currently supported in
 - `disabled` do not look for the dependency and always return 'not-found'.
 
 When getting the value of this type of option using `get_option()`, a special
-object is returned instead of the string representation of the option's value.
-That object has three methods returning boolean and taking no argument:
-`enabled()`, `disabled()`, and `auto()`.
+[feature option object](Reference-manual.md#feature-option-object)
+is returned instead of the string representation of the option's value.
+This object can be passed to `required`:
 
 ```meson
 d = dependency('foo', required : get_option('myfeature'))
@@ -94,6 +94,21 @@ if d.found()
 endif
 ```
 
+To check the value of the feature, the object has three methods
+returning a boolean and taking no argument:
+
+- `.enabled()`
+- `.disabled()`
+- `.auto()`
+
+This is useful for custom code depending on the feature:
+
+```meson
+if get_option('myfeature').enabled()
+  # ...
+endif
+```
+
 If the value of a `feature` option is set to `auto`, that value is overridden by
 the global `auto_features` option (which defaults to `auto`). This is intended
 to be used by packagers who want to have full control on which dependencies are
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index acb7e39..475b711 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -846,8 +846,10 @@ configuration as-is, which may be absolute, or relative to `prefix`.
 if you need the absolute path to one of these e.g. to use in a define
 etc., you should use `get_option('prefix') / get_option('localstatedir')`
 
-For options of type `feature` a special object is returned instead of
-a string.  See [`feature` options](Build-options.md#features)
+For options of type `feature` a
+[feature option object](#feature-option-object)
+is returned instead of a string.
+See [`feature` options](Build-options.md#features)
 documentation for more details.
 
 ### get_variable()
@@ -2472,6 +2474,16 @@ library. This object has the following methods:
    object will only inherit other attributes from its parent as
    controlled by keyword arguments.
 
+### Feature option object
+
+The following methods are defined for all [`feature` options](Build-options.md#features):
+
+- `enabled()` returns whether the feature was set to `'enabled'`
+- `disabled()` returns whether the feature was set to `'disabled'`
+- `auto()` returns whether the feature was set to `'auto'`
+
+Feature options are available since 0.47.0.
+
 ### `generator` object
 
 This object is returned by [`generator()`](#generator) and contains a