return(): Propagate variables to result scope

Fixes: #23871

3 files changed, 39 insertions, 4 deletions

diff --git a/Help/command/block.rst b/Help/command/block.rst
index f9d85c8..9d37deb 100644
--- a/Help/command/block.rst
+++ b/Help/command/block.rst
@@ -71,4 +71,5 @@ See Also
 ^^^^^^^^
 
   * :command:`endblock`
+  * :command:`return`
   * :command:`cmake_policy`
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`
diff --git a/Help/command/set.rst b/Help/command/set.rst
index aa2ea55..5e05d9b 100644
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@@ -30,9 +30,9 @@ applicable to the case at hand). The previous state of the variable's value
 stays the same in the current scope (e.g., if it was undefined before, it is
 still undefined and if it had a value, it is still that value).
 
-The :command:`block(PROPAGATE)` command can be used as an alternate method to
-:command:`set(PARENT_SCOPE)` and :command:`unset(PARENT_SCOPE)` commands to
-update the parent scope.
+The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands can
+be used as an alternate method to the :command:`set(PARENT_SCOPE)` and
+:command:`unset(PARENT_SCOPE)` commands to update the parent scope.
 
 Set Cache Entry
 ^^^^^^^^^^^^^^^