Merge topic 'doc-reStructuredText'

7038a93 Modules/readme.txt: Update steps to add module documentation
a77e308 CPack: Replace #<type> markup with reStructuredText equivalent
e7ca48f Help: Factor out cmake-generator-expressions manual page
97e8650 Help: Factor out COMPILE_DEFINITIONS disclaimer duplication
8982161 Help: Factor out find_* command duplication
30b2186 Help: Factor out *_OUTPUT_(NAME|DIRECTORY).rst duplication
bfe07aa Build Help documentation during CMake build using Sphinx
53ded59 Drop unused builtin documentation APIs
0c39a75 Drop the 'Full' field from cmDocumentationEntry
e33d8d2 Drop builtin command documentation
399e9c4 Drop builtin property documentation
6035c04 get_property: Drop test for builtin property documentation
80a3273 Drop all documentation formatters except Usage
b336a1eb Teach COMPATIBLE_INTERFACE_* checks to use Help .rst documents
ec6df36 Teach --help-* options to load documentation from .rst files
25f2877 Add class cmRST to do basic reStructuredText processing
...

1 files changed, 31 insertions, 0 deletions

diff --git a/Help/command/function.rst b/Help/command/function.rst
new file mode 100644
index 0000000..b18e03c
--- /dev/null
+++ b/Help/command/function.rst
@@ -0,0 +1,31 @@
+function
+--------
+
+Start recording a function for later invocation as a command.
+
+::
+
+  function(<name> [arg1 [arg2 [arg3 ...]]])
+    COMMAND1(ARGS ...)
+    COMMAND2(ARGS ...)
+    ...
+  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.
+
+A function opens a new scope: see set(var PARENT_SCOPE) for details.
+
+See the cmake_policy() command documentation for the behavior of
+policies inside functions.