return(): Propagate variables to result scope

Fixes: #23871

1 files changed, 35 insertions, 1 deletions

diff --git a/Help/command/return.rst b/Help/command/return.rst
index ec009d8..029fd05 100644
--- a/Help/command/return.rst
+++ b/Help/command/return.rst
@@ -5,7 +5,7 @@ Return from a file, directory or function.
 
 .. code-block:: cmake
 
-  return()
+  return([PROPAGATE <var-name>...])
 
 Returns from a file, directory or function.  When this command is
 encountered in an included file (via :command:`include` or
@@ -16,5 +16,39 @@ deferred calls scheduled by :command:`cmake_language(DEFER)` are invoked and
 control is returned to the parent directory if there is one.  If return is
 called in a function, control is returned to the caller of the function.
 
+``PROPAGATE``
+  .. versionadded:: 3.25
+
+  This option set or unset the specified variables in the parent directory or
+  function caller scope. This is equivalent to :command:`set(PARENT_SCOPE)` or
+  :command:`unset(PARENT_SCOPE)` commands.
+
+  The option ``PROPAGATE`` can be very useful in conjunction with the
+  :command:`block` command because the :command:`return` will cross over
+  various scopes created by the :command:`block` commands.
+
+  .. code-block:: cmake
+
+    function(MULTI_SCOPES RESULT_VARIABLE)
+      block(SCOPE_FOR VARIABLES)
+        # here set(PARENT_SCOPE) is not usable because it will not set the
+        # variable in the caller scope but in the parent scope of the block()
+        set(${RESULT_VARIABLE} "new-value")
+        return(PROPAGATE ${RESULT_VARIABLE})
+      endblock()
+    endfunction()
+
+    set(MY_VAR "initial-value")
+    multi_scopes(MY_VAR)
+    # here MY_VAR will holds "new-value"
+
+Policy :policy:`CMP0140` controls the behavior regarding the arguments of the
+command.
+
 Note that a :command:`macro <macro>`, unlike a :command:`function <function>`,
 is expanded in place and therefore cannot handle ``return()``.
+
+See Also
+^^^^^^^^
+
+  * :command:`block`