From 7a614977f9443146e8b423b6dc5a11a7c79862ce Mon Sep 17 00:00:00 2001
From: Ben Boeckel <ben.boeckel@kitware.com>
Date: Tue, 29 Mar 2022 16:26:26 -0400
Subject: CMakeDependentOption: improve documentation

This makes it far clearer that `<depends>` is a list up front instead of
burying the lede because a list is generally "trivially true" in CMake[1].
Also clarify that `<force>` is only available as a local variable and if
queried outside of the "scope" of the `cmake_dependent_option` call,
will get the stored user cache value.

[1] The exception being when the last entry ends in `-NOTFOUND`.

Suggested-by: Rui Oliveira
---
 Modules/CMakeDependentOption.cmake | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/Modules/CMakeDependentOption.cmake b/Modules/CMakeDependentOption.cmake
index b7c478f..ac0e262 100644
--- a/Modules/CMakeDependentOption.cmake
+++ b/Modules/CMakeDependentOption.cmake
@@ -16,13 +16,18 @@ conditions are true.
 
     cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>)
 
-  Makes ``<option>`` available to the user if ``<depends>`` is true. When
-  ``<option>`` is available, the given ``<help_text>`` and initial ``<value>``
-  are used. If the ``<depends>`` condition is not true, ``<option>`` will not be
-  presented and will always have the value given by ``<force>``. Any value set by
-  the user is preserved for when the option is presented again. In case ``<depends>``
-  is a :ref:`semicolon-separated list <CMake Language Lists>`, all elements must
-  be true in order to initialize ``<option>`` with ``<value>``.
+  Makes ``<option>`` available to the user if the
+  :ref:`semicolon-separated list <CMake Language Lists>` of conditions in
+  ``<depends>`` are all true.  Otherwise, a local variable named ``<option>``
+  is set to ``<force>``.
+
+  When ``<option>`` is available, the given ``<help_text>`` and initial
+  ``<value>`` are used. Otherwise, any value set by the user is preserved for
+  when ``<depends>`` is satisfied in the future.
+
+  Note that the ``<option>`` variable only has a value which satisfies the
+  ``<depends>`` condition within the scope of the caller because it is a local
+  variable.
 
 Example invocation:
 
-- 
cgit v0.12