Merge topic 'patch-condition-arguments-examples'

70ccf47e60 Help: Add more examples for condition syntax in commands

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10073

Modules/CMakeDependentOption.cmake

@@ -29,7 +29,14 @@ conditions are true.
   ``<depends>`` condition within the scope of the caller because it is a local
   variable.
 
-Example invocation:
+.. versionadded:: 3.22
+
+  Full :ref:`Condition Syntax` is now supported.  See policy :policy:`CMP0127`.
+
+Examples
+^^^^^^^^
+
+Semicolon-separated list of conditions:
 
 .. code-block:: cmake
 
@@ -41,10 +48,18 @@ hides the option from the user. If the status of ``USE_BAR`` or ``USE_ZOT``
 ever changes, any value for the ``USE_FOO`` option is saved so that when the
 option is re-enabled it retains its old value.
 
-.. versionadded:: 3.22
+Full condition syntax:
 
-  Full :ref:`Condition Syntax` is now supported.  See policy :policy:`CMP0127`.
+.. code-block:: cmake
+
+  cmake_dependent_option(USE_FOO "Use Foo" ON "USE_A AND (USE_B OR USE_C)" OFF)
 
+Similar to the previous example, if the argument with full condition syntax
+evaluates to true, this provides an option called ``USE_FOO`` that defaults to
+ON. Otherwise, it sets ``USE_FOO`` to OFF and hides the option from the user in
+the GUI. When condition changes, option is saved in similar way as described
+above. This enables using entire condition syntax as being the ``if`` clause
+argument, such as grouping conditions with parens and similar.
 #]=======================================================================]
 
 macro(CMAKE_DEPENDENT_OPTION option doc default depends force)

Modules/FeatureSummary.cmake

@@ -636,7 +636,36 @@ endfunction()
   .. code-block:: cmake
 
      option(WITH_FOO "Help for foo" ON)
-     add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
+     add_feature_info(Foo WITH_FOO "this feature provides very cool stuff")
+
+  Example for setting feature info based on a list of conditions:
+
+  .. code-block:: cmake
+
+    option(WITH_FOO "Help for foo" ON)
+    option(WITH_BAR "Help for bar" OFF)
+    add_feature_info(
+      FooBar
+      "WITH_FOO;NOT WITH_BAR"
+      "this feature is enabled when WITH_FOO is ON and WITH_BAR turned OFF"
+    )
+
+  Example for setting feature info depending on a full condition syntax:
+
+  Unlike semicolon-separated list of conditions, this enables using entire
+  condition syntax as being the ``if`` clause argument, such as grouping
+  conditions with parens and similar.
+
+  .. code-block:: cmake
+
+    option(WITH_FOO "Help for foo" ON)
+    option(WITH_BAR "Help for bar" ON)
+    option(WITH_BAZ "Help for baz" OFF)
+    add_feature_info(
+      FooBarBaz
+      "WITH_FOO AND (WITH_BAR OR WITH_BAZ)"
+      "this feature is enabled when the entire condition is true"
+    )
 #]=======================================================================]
 function(ADD_FEATURE_INFO _name _depends _desc)
   cmake_policy(GET CMP0183 _CDO_CMP0183