Merge topic 'docs-CMAKE_CURRENT_FUNCTION' into release-3.17

10ee9611f0 Help: Improve wording of CMAKE_CURRENT_FUNCTION_LIST_DIR docs
22fbc404a7 Help: Add cross-references for CMAKE_CURRENT_FUNCTION* docs
d2b139687a Help: Minor grammar cleanups of CMAKE_CURRENT_FUNCTION* docs

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Brad King <brad.king@kitware.com>
Acked-by: Alex Turbov <i.zaufi@gmail.com>
Merge-request: !4595

5 files changed, 46 insertions, 25 deletions

diff --git a/Help/command/macro.rst b/Help/command/macro.rst
index 3f6f2f9..008d049 100644
--- a/Help/command/macro.rst
+++ b/Help/command/macro.rst
@@ -95,7 +95,7 @@ Unlike a function, the :variable:`CMAKE_CURRENT_FUNCTION`,
 :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`,
 :variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`,
 :variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` variables are not
-set for macro.
+set for a macro.
 
 .. _`Argument Caveats`:
 
diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION.rst b/Help/variable/CMAKE_CURRENT_FUNCTION.rst
index aa2936c..fb7f610 100644
--- a/Help/variable/CMAKE_CURRENT_FUNCTION.rst
+++ b/Help/variable/CMAKE_CURRENT_FUNCTION.rst
@@ -2,5 +2,9 @@ CMAKE_CURRENT_FUNCTION
 ----------------------
 
 When executing code inside a :command:`function`, this variable
-contains the name of the current function.  It can be used for
+contains the name of the current function.  It can be useful for
 diagnostic or debug messages.
+
+See also :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`,
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` and
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`.
diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst
index 0119381..44ae1e5 100644
--- a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst
+++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst
@@ -2,32 +2,40 @@ CMAKE_CURRENT_FUNCTION_LIST_DIR
 -------------------------------
 
 When executing code inside a :command:`function`, this variable
-contains the full directory of the listfile defining the current function.
+contains the full directory of the listfile that defined the current function.
 
-It is quite common practice in CMake that modules use some additional files
-(e.g., templates to render).  And the code typically did the following:
+It is quite common practice in CMake for modules to use some additional files,
+such as templates to be copied in after substituting CMake variables.
+In such cases, a function needs to know where to locate those files in a way
+that doesn't depend on where the function is called.  Without
+``CMAKE_CURRENT_FUNCTION_LIST_DIR``, the code to do that would typically use
+the following pattern:
 
 .. code-block:: cmake
-    :caption: Bad
 
-    set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}")
+  set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}")
 
-    function(foo)
-      configure_file(
-        "${_THIS_MODULE_BASE_DIR}/some.template.in"
-        some.output
-      )
-    endfunction()
+  function(foo)
+    configure_file(
+      "${_THIS_MODULE_BASE_DIR}/some.template.in"
+      some.output
+    )
+  endfunction()
 
-Using this variable inside a function eliminates the neccessity of the
-additional one with "global" scope:
+Using ``CMAKE_CURRENT_FUNCTION_LIST_DIR`` inside the function instead
+eliminates the need for the extra variable which would otherwise be visible
+outside the function's scope.
+The above example can be written in the more concise and more robust form:
 
 .. code-block:: cmake
-    :caption: Good
-
-    function(foo)
-      configure_file(
-        "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in"
-        some.output
-      )
-    endfunction()
+
+  function(foo)
+    configure_file(
+      "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in"
+      some.output
+    )
+  endfunction()
+
+See also :variable:`CMAKE_CURRENT_FUNCTION`,
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` and
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`.
diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst
index d2c846a..c737af9 100644
--- a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst
+++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst
@@ -2,4 +2,8 @@ CMAKE_CURRENT_FUNCTION_LIST_FILE
 --------------------------------
 
 When executing code inside a :command:`function`, this variable
-contains the full path to the listfile declaring a current function.
+contains the full path to the listfile that defined the current function.
+
+See also :variable:`CMAKE_CURRENT_FUNCTION`,
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` and
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`.
diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst
index 5a7cd13..ad6282e 100644
--- a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst
+++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst
@@ -2,4 +2,9 @@ CMAKE_CURRENT_FUNCTION_LIST_LINE
 --------------------------------
 
 When executing code inside a :command:`function`, this variable
-contains the line number in the listfile where a current function has defined.
+contains the line number in the listfile where the current function
+was defined.
+
+See also :variable:`CMAKE_CURRENT_FUNCTION`,
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` and
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`.