Help: Refine the .rst formatting of macro and function documentation

parent 1c3799b1
function
--------
Start recording a function for later invocation as a command.
::
Start recording a function for later invocation as a command::
function(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...)
......@@ -11,21 +9,24 @@ Start recording a function for later invocation as a command.
...
endfunction(<name>)
Define a function named <name> that takes arguments named arg1 arg2
arg3 (...). Commands listed after function, but before the matching
endfunction, are not invoked until the function is invoked. When it
is invoked, the commands recorded in the function are first modified
by replacing formal parameters (${arg1}) with the arguments passed,
and then invoked as normal commands. In addition to referencing the
formal parameters you can reference the variable ARGC which will be
set to the number of arguments passed into the function as well as
ARGV0 ARGV1 ARGV2 ... which will have the actual values of the
arguments passed in. This facilitates creating functions with
optional arguments. Additionally ARGV holds the list of all arguments
given to the function and ARGN holds the list of arguments past the
last expected argument.
Define a function named ``<name>`` that takes arguments named ``arg1``,
``arg2``, ``arg3``, (...).
Commands listed after function, but before the matching
:command:`endfunction()`, are not invoked until the function is invoked.
When it is invoked, the commands recorded in the function are first
modified by replacing formal parameters (``${arg1}``) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
``ARGC`` variable which will be set to the number of arguments passed
into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which
will have the actual values of the arguments passed in.
This facilitates creating functions with optional arguments.
Additionally ``ARGV`` holds the list of all arguments given to the
function and ``ARGN`` holds the list of arguments past the last expected
argument.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
details.
See the cmake_policy() command documentation for the behavior of
policies inside functions.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside functions.
macro
-----
Start recording a macro for later invocation as a command.
::
Start recording a macro for later invocation as a command::
macro(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...)
......@@ -11,22 +9,24 @@ Start recording a macro for later invocation as a command.
...
endmacro(<name>)
Define a macro named <name> that takes arguments named arg1 arg2 arg3
(...). Commands listed after macro, but before the matching endmacro,
are not invoked until the macro is invoked. When it is invoked, the
commands recorded in the macro are first modified by replacing formal
parameters (``${arg1}``) with the arguments passed, and then invoked as
normal commands. In addition to referencing the formal parameters you
can reference the values ``${ARGC}`` which will be set to the number of
arguments passed into the function as well as ``${ARGV0}`` ``${ARGV1}``
``${ARGV2}`` ... which will have the actual values of the arguments
passed in. This facilitates creating macros with optional arguments.
Define a macro named ``<name>`` that takes arguments named ``arg1``,
``arg2``, ``arg3``, (...).
Commands listed after macro, but before the matching
:command:`endmacro()`, are not invoked until the macro is invoked.
When it is invoked, the commands recorded in the macro are first
modified by replacing formal parameters (``${arg1}``) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
values ``${ARGC}`` which will be set to the number of arguments passed
into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
... which will have the actual values of the arguments passed in.
This facilitates creating macros with optional arguments.
Additionally ``${ARGV}`` holds the list of all arguments given to the
macro and ``${ARGN}`` holds the list of arguments past the last expected
argument.
See the cmake_policy() command documentation for the behavior of
policies inside macros.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside macros.
Macro Argument Caveats
^^^^^^^^^^^^^^^^^^^^^^
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment