optinterpreter: Add deprecated kwarg

It can be either:
- boolean: the option is completely deprecated.
- list: some choices are deprecated.
- dict: some choices are deprecated and replaced by another.

Fixes: #7444

1 files changed, 26 insertions, 0 deletions

diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md
index 86f1001..4b66cbf 100644
--- a/docs/markdown/Build-options.md
+++ b/docs/markdown/Build-options.md
@@ -123,6 +123,32 @@ only the few they don't want, if any.
 
 This type is available since version 0.47.0
 
+## Deprecated options
+
+Since *0.60.0*
+
+Project options can be marked as deprecated and Meson will warn when user sets a
+value to it. It is also possible to deprecate only some of the choices, and map
+deprecated values to a new value.
+
+```meson
+# Option fully deprecated, it warns when any value is set.
+option('o1', type: 'boolean', deprecated: true)
+
+# One of the choices is deprecated, it warns only when 'a' is in the list of values.
+option('o2', type: 'array', choices: ['a', 'b'], deprecated: ['a'])
+
+# One of the choices is deprecated, it warns only when 'a' is in the list of values
+# and replace it by 'c'.
+option('o3', type: 'array', choices: ['a', 'b', 'c'], deprecated: {'a': 'c'})
+
+# A boolean option has been replaced by a feature, old true/false values are remapped.
+option('o4', type: 'feature', deprecated: {'true': 'enabled', 'false': 'disabled'})
+
+# A feature option has been replaced by a boolean, enabled/disabled/auto values are remapped.
+option('o5', type: 'boolean', deprecated: {'enabled': 'true', 'disabled': 'false', 'auto': 'false'})
+```
+
 ## Using build options
 
 ```meson