Merge topic 'cmake-syntax-updates'

2945814 cmRST: Teach cmake-module directive to scan bracket comments
8bb2ee9 cmake-developer.7: Improve flow of module documentation instructions
efcf318 Add \-continuation to CMake language quoted arguments

1 files changed, 39 insertions, 22 deletions

diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index eace3a4..198a240 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -230,30 +230,46 @@ The ``Modules`` directory contains CMake-language ``.cmake`` module files.
 Module Documentation
 --------------------
 
-To add a module to the CMake documentation, follow these steps:
+To document CMake module ``Modules/<module-name>.cmake``, modify
+``Help/manual/cmake-modules.7.rst`` to reference the module in the
+``toctree`` directive, in sorted order, as::
 
-1. Add file ``Help/module/<module-name>.rst`` containing just the line::
+ /module/<module-name>
 
-    .. cmake-module:: ../../Modules/<module-name>.cmake
+Then add the module document file ``Help/module/<module-name>.rst``
+containing just the line::
 
-2. Modify ``Help/manual/cmake-modules.7.rst`` to reference the module in the
-   toctree directive as::
+ .. cmake-module:: ../../Modules/<module-name>.cmake
 
-    /module/<module-name>
+The ``cmake-module`` directive will scan the module file to extract
+reStructuredText markup from comment blocks that start in ``.rst:``.
+Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form:
 
-   Keep the toctree in sorted order!
+.. code-block:: cmake
+
+ #.rst:
+ # <module-name>
+ # -------------
+ #
+ # <reStructuredText documentation of module>
+
+or a bracket-comment of the form:
+
+.. code-block:: cmake
 
-3. Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form::
+ #[[.rst:
+ <module-name>
+ -------------
+
+ <reStructuredText documentation of module>
+ #]]
 
-    #.rst:
-    # <module-name>
-    # -------------
-    #
-    # ...reStructuredText documentation of module...
+Any number of ``=`` may be used in the opening and closing brackets
+as long as they match.  Content on the line containing the closing
+bracket is excluded if and only if the line starts in ``#``.
 
-   Comment blocks starting with the line ``#.rst:`` may appear anywhere
-   in the file.  The ``cmake-module`` directive used above will scan the
-   file to extract reStructuredText markup from such comments.
+Additional such ``.rst:`` comments may appear anywhere in the module file.
+All such comments must start with ``#`` in the first column.
 
 For example, a ``Modules/Findxxx.cmake`` module may contain:
 
@@ -275,12 +291,13 @@ For example, a ``Modules/Findxxx.cmake`` module may contain:
 
  <code>
 
- #.rst:
- # .. command:: xxx_do_something
- #
- #  This command does something for Xxx::
- #
- #   xxx_do_something(some arguments)
+ #[========================================[.rst:
+ .. command:: xxx_do_something
+
+  This command does something for Xxx::
+
+   xxx_do_something(some arguments)
+ #]========================================]
  macro(xxx_do_something)
    <code>
  endmacro()