Help: describe differences between macro and function.

2 files changed, 38 insertions, 10 deletions

diff --git a/Help/command/function.rst b/Help/command/function.rst
index 7b10381..53ba754 100644
--- a/Help/command/function.rst
+++ b/Help/command/function.rst
@@ -23,6 +23,9 @@ details.
 See the :command:`cmake_policy()` command documentation for the behavior
 of policies inside functions.
 
+See the :command:`macro()` command documentation for differences
+between CMake functions and macros.
+
 Invocation
 ^^^^^^^^^^
 
diff --git a/Help/command/macro.rst b/Help/command/macro.rst
index 7450929..42a99fc 100644
--- a/Help/command/macro.rst
+++ b/Help/command/macro.rst
@@ -21,6 +21,9 @@ argument of the opening ``macro`` command.
 See the :command:`cmake_policy()` command documentation for the behavior
 of policies inside macros.
 
+See the :ref:`Macro vs Function` section below for differences
+between CMake macros and :command:`functions <function>`.
+
 Invocation
 ^^^^^^^^^^
 
@@ -65,13 +68,36 @@ behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only
 way to ensure that ``${ARGV#}`` was passed to the function as an extra
 argument.
 
+.. _`Macro vs Function`:
+
+Macro vs Function
+^^^^^^^^^^^^^^^^^
+
+The ``macro`` command is very similar to the :command:`function` command.
+Nonetheless, there are a few important differences.
+
+In a function, ``ARGC``, ``ARGC`` and ``ARGV0``, ``ARGV1``, ... are
+true variables in the usual CMake sense.  In a macro, they are not.
+They are string replacements much like the C preprocessor would do
+with a macro.  This has a number of consequences, as explained in
+the :ref:`Argument Caveats` section below.
+
+Another difference between macros and functions is the control flow.
+A function is executed by transfering control from the calling
+statement to the function body.  A macro is executed as if the macro
+body were pasted in place of the calling statement.  This has for
+consequence that a :command:`return()` in a macro body does not
+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.
+
+.. _`Argument Caveats`:
+
 Argument Caveats
 ^^^^^^^^^^^^^^^^
 
-Note that the parameters to a macro and values such as ``ARGN`` are
-not variables in the usual CMake sense.  They are string
-replacements much like the C preprocessor would do with a macro.
-Therefore you will NOT be able to use commands like
+Since ``ARGC``, ``ARGC``, ``ARGV0`` etc are not variables,
+you will NOT be able to use commands like
 
 .. code-block:: cmake
 
@@ -80,12 +106,11 @@ Therefore you will NOT be able to use commands like
  if(ARGC GREATER 2) # ARGC is not a variable
  foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
 
-In the first case, you can use ``if(${ARGV1})``.
-In the second and third case, the proper way to check if an optional
-variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``.
-In the last case, you can use ``foreach(loop_var ${ARGN})`` but this
-will skip empty arguments.
-If you need to include them, you can use
+In the first case, you can use ``if(${ARGV1})``.  In the second and
+third case, the proper way to check if an optional variable was
+passed to the macro is to use ``if(${ARGC} GREATER 2)``.  In the
+last case, you can use ``foreach(loop_var ${ARGN})`` but this will
+skip empty arguments.  If you need to include them, you can use
 
 .. code-block:: cmake