cmFunctionCommand: Introduce CMAKE_CURRENT_FUNCTION* variables

`CMAKE_CURRENT_FUNCTION`
  Can be used for diagnostic or debugging messages like the
  `__PRETTY_FUNCTION__` macro of GCC.

`CMAKE_CURRENT_FUNCTION_LIST_DIR`
  Eliminates the necessity of the additional "global"
  variables inside a module used to access additional "resource"
  files from functions defined in the module.

...

Help/command/macro.rst

@@ -91,6 +91,12 @@ just terminate execution of the macro; rather, control is returned
 from the scope of the macro call.  To avoid confusion, it is recommended
 to avoid :command:`return()` in macros altogether.
 
+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.
+
 .. _`Argument Caveats`:
 
 Argument Caveats

Help/manual/cmake-variables.7.rst

@@ -37,6 +37,10 @@ Variables that Provide Information
    /variable/CMAKE_CROSSCOMPILING_EMULATOR
    /variable/CMAKE_CTEST_COMMAND
    /variable/CMAKE_CURRENT_BINARY_DIR
+   /variable/CMAKE_CURRENT_FUNCTION
+   /variable/CMAKE_CURRENT_FUNCTION_LIST_DIR
+   /variable/CMAKE_CURRENT_FUNCTION_LIST_FILE
+   /variable/CMAKE_CURRENT_FUNCTION_LIST_LINE
    /variable/CMAKE_CURRENT_LIST_DIR
    /variable/CMAKE_CURRENT_LIST_FILE
    /variable/CMAKE_CURRENT_LIST_LINE

Help/release/dev/CMAKE_CURRENT_FUNCTION.rst

@@ -0,0 +1,9 @@
+CMAKE_CURRENT_FUNCTION
+----------------------
+
+* Define the following variables inside a function:
+
+    - :variable:`CMAKE_CURRENT_FUNCTION`
+    - :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`
+    - :variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`
+    - :variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`

Help/variable/CMAKE_CURRENT_FUNCTION.rst

@@ -0,0 +1,6 @@
+CMAKE_CURRENT_FUNCTION
+----------------------
+
+When executing code inside a :command:`function`, this variable
+contains the name of the current function.  It can be used for
+diagnostic or debug messages.

Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst

@@ -0,0 +1,33 @@
+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.
+
+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:
+
+.. code-block:: cmake
+    :caption: Bad
+
+    set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}")
+
+    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:
+
+.. code-block:: cmake
+    :caption: Good
+
+    function(foo)
+      configure_file(
+        "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in"
+        some.output
+      )
+    endfunction()

Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst

@@ -0,0 +1,5 @@
+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.

Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst

@@ -0,0 +1,5 @@
+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.