Modules docs: move rst docs into bracket comments

CMake >= 3.0 supports bracket comments, and the reStructuredText
integration code in sphinx/ext/ecm.py already supports extracting
the docs from a bracket comment instead.
Editing documentation without leading line comment markers is more simple,
e,g. when reflowing text over lines.

With ECM meanwhile requiring CMake 3.5 now it is possible to switch
(and thus follow also the approach used by cmake itself).

NO_CHANGELOG

1 files changed, 114 insertions, 114 deletions

diff --git a/modules/ECMGenerateHeaders.cmake b/modules/ECMGenerateHeaders.cmake
index d5332e58..9099cb5a 100644
--- a/modules/ECMGenerateHeaders.cmake
+++ b/modules/ECMGenerateHeaders.cmake
@@ -1,123 +1,123 @@
-#.rst:
-# ECMGenerateHeaders
-# ------------------
-#
-# Generate C/C++ CamelCase forwarding headers.
-#
-# ::
-#
-#   ecm_generate_headers(<camelcase_forwarding_headers_var>
-#       HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
-#       [ORIGINAL <CAMELCASE|LOWERCASE>]
-#       [HEADER_EXTENSION <header_extension>]
-#       [OUTPUT_DIR <output_dir>]
-#       [PREFIX <prefix>]
-#       [REQUIRED_HEADERS <variable>]
-#       [COMMON_HEADER <HeaderName>]
-#       [RELATIVE <relative_path>])
-#
-# For each CamelCase header name passed to HEADER_NAMES, a file of that name
-# will be generated that will include a version with ``.h`` or, if set,
-# ``.<header_extension>`` appended.
-# For example, the generated header ``ClassA`` will include ``classa.h`` (or
-# ``ClassA.h``, see ORIGINAL).
-# If a CamelCaseName consists of multiple comma-separated files, e.g.
-# ``ClassA,ClassB,ClassC``, then multiple camelcase header files will be
-# generated which are redirects to the first header file.
-# The file locations of these generated headers will be stored in
-# <camelcase_forwarding_headers_var>.
-#
-# ORIGINAL specifies how the name of the original header is written: lowercased
-# or also camelcased.  The default is LOWERCASE. Since 1.8.0.
-#
-# HEADER_EXTENSION specifies what file name extension is used for the header
-# files.  The default is "h". Since 5.48.0.
-#
-# PREFIX places the generated headers in subdirectories.  This should be a
-# CamelCase name like ``KParts``, which will cause the CamelCase forwarding
-# headers to be placed in the ``KParts`` directory (e.g. ``KParts/Part``).  It
-# will also, for the convenience of code in the source distribution, generate
-# forwarding headers based on the original names (e.g. ``kparts/part.h``).  This
-# allows includes like ``"#include <kparts/part.h>"`` to be used before
-# installation, as long as the include_directories are set appropriately.
-#
-# OUTPUT_DIR specifies where the files will be generated; this should be within
-# the build directory. By default, ``${CMAKE_CURRENT_BINARY_DIR}`` will be used.
-# This option can be used to avoid file conflicts.
-#
-# REQUIRED_HEADERS specifies an output variable name where all the required
-# headers will be appended so that they can be installed together with the
-# generated ones.  This is mostly intended as a convenience so that adding a new
-# header to a project only requires specifying the CamelCase variant in the
-# CMakeLists.txt file; the original variant will then be added to this
-# variable.
-#
-# COMMON_HEADER generates an additional convenience header which includes all
-# other header files.
-#
-# The RELATIVE argument indicates where the original headers can be found
-# relative to CMAKE_CURRENT_SOURCE_DIR.  It does not affect the generated
-# CamelCase forwarding files, but ecm_generate_headers() uses it when checking
-# that the original header exists, and to generate originally named forwarding
-# headers when PREFIX is set.
-#
-# To allow other parts of the source distribution (eg: tests) to use the
-# generated headers before installation, it may be desirable to set the
-# INCLUDE_DIRECTORIES property for the library target to output_dir.  For
-# example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you could do
-#
-# .. code-block:: cmake
-#
-#   target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
-#
-# Example usage (without PREFIX):
-#
-# .. code-block:: cmake
-#
-#   ecm_generate_headers(
-#       MyLib_FORWARDING_HEADERS
-#       HEADERS
-#           MLFoo
-#           MLBar
-#           # etc
-#       REQUIRED_HEADERS MyLib_HEADERS
-#       COMMON_HEADER MLGeneral
-#   )
-#   install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
-#           DESTINATION ${CMAKE_INSTALL_PREFIX}/include
-#           COMPONENT Devel)
-#
-# Example usage (with PREFIX):
-#
-# .. code-block:: cmake
-#
-#   ecm_generate_headers(
-#       MyLib_FORWARDING_HEADERS
-#       HEADERS
-#           Foo
-#           # several classes are contained in bar.h, so generate
-#           # additional files
-#           Bar,BarList
-#           # etc
-#       PREFIX MyLib
-#       REQUIRED_HEADERS MyLib_HEADERS
-#   )
-#   install(FILES ${MyLib_FORWARDING_HEADERS}
-#           DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
-#           COMPONENT Devel)
-#   install(FILES ${MyLib_HEADERS}
-#           DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
-#           COMPONENT Devel)
-#
-# Since pre-1.0.0.
-
-#=============================================================================
 # SPDX-FileCopyrightText: 2013 Aleix Pol Gonzalez <aleixpol@blue-systems.com>
 # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kdemail.net>
 # SPDX-FileCopyrightText: 2015 Patrick Spendrin <patrick.spendrin@kdab.com>
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
+#[=======================================================================[.rst:
+ECMGenerateHeaders
+------------------
+
+Generate C/C++ CamelCase forwarding headers.
+
+::
+
+  ecm_generate_headers(<camelcase_forwarding_headers_var>
+      HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
+      [ORIGINAL <CAMELCASE|LOWERCASE>]
+      [HEADER_EXTENSION <header_extension>]
+      [OUTPUT_DIR <output_dir>]
+      [PREFIX <prefix>]
+      [REQUIRED_HEADERS <variable>]
+      [COMMON_HEADER <HeaderName>]
+      [RELATIVE <relative_path>])
+
+For each CamelCase header name passed to HEADER_NAMES, a file of that name
+will be generated that will include a version with ``.h`` or, if set,
+``.<header_extension>`` appended.
+For example, the generated header ``ClassA`` will include ``classa.h`` (or
+``ClassA.h``, see ORIGINAL).
+If a CamelCaseName consists of multiple comma-separated files, e.g.
+``ClassA,ClassB,ClassC``, then multiple camelcase header files will be
+generated which are redirects to the first header file.
+The file locations of these generated headers will be stored in
+<camelcase_forwarding_headers_var>.
+
+ORIGINAL specifies how the name of the original header is written: lowercased
+or also camelcased.  The default is LOWERCASE. Since 1.8.0.
+
+HEADER_EXTENSION specifies what file name extension is used for the header
+files.  The default is "h". Since 5.48.0.
+
+PREFIX places the generated headers in subdirectories.  This should be a
+CamelCase name like ``KParts``, which will cause the CamelCase forwarding
+headers to be placed in the ``KParts`` directory (e.g. ``KParts/Part``).  It
+will also, for the convenience of code in the source distribution, generate
+forwarding headers based on the original names (e.g. ``kparts/part.h``).  This
+allows includes like ``"#include <kparts/part.h>"`` to be used before
+installation, as long as the include_directories are set appropriately.
+
+OUTPUT_DIR specifies where the files will be generated; this should be within
+the build directory. By default, ``${CMAKE_CURRENT_BINARY_DIR}`` will be used.
+This option can be used to avoid file conflicts.
+
+REQUIRED_HEADERS specifies an output variable name where all the required
+headers will be appended so that they can be installed together with the
+generated ones.  This is mostly intended as a convenience so that adding a new
+header to a project only requires specifying the CamelCase variant in the
+CMakeLists.txt file; the original variant will then be added to this
+variable.
+
+COMMON_HEADER generates an additional convenience header which includes all
+other header files.
+
+The RELATIVE argument indicates where the original headers can be found
+relative to CMAKE_CURRENT_SOURCE_DIR.  It does not affect the generated
+CamelCase forwarding files, but ecm_generate_headers() uses it when checking
+that the original header exists, and to generate originally named forwarding
+headers when PREFIX is set.
+
+To allow other parts of the source distribution (eg: tests) to use the
+generated headers before installation, it may be desirable to set the
+INCLUDE_DIRECTORIES property for the library target to output_dir.  For
+example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you could do
+
+.. code-block:: cmake
+
+  target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
+
+Example usage (without PREFIX):
+
+.. code-block:: cmake
+
+  ecm_generate_headers(
+      MyLib_FORWARDING_HEADERS
+      HEADERS
+          MLFoo
+          MLBar
+          # etc
+      REQUIRED_HEADERS MyLib_HEADERS
+      COMMON_HEADER MLGeneral
+  )
+  install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
+          DESTINATION ${CMAKE_INSTALL_PREFIX}/include
+          COMPONENT Devel)
+
+Example usage (with PREFIX):
+
+.. code-block:: cmake
+
+  ecm_generate_headers(
+      MyLib_FORWARDING_HEADERS
+      HEADERS
+          Foo
+          # several classes are contained in bar.h, so generate
+          # additional files
+          Bar,BarList
+          # etc
+      PREFIX MyLib
+      REQUIRED_HEADERS MyLib_HEADERS
+  )
+  install(FILES ${MyLib_FORWARDING_HEADERS}
+          DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
+          COMPONENT Devel)
+  install(FILES ${MyLib_HEADERS}
+          DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
+          COMPONENT Devel)
+
+Since pre-1.0.0.
+#]=======================================================================]
+
 include(CMakeParseArguments)
 
 function(ECM_GENERATE_HEADERS camelcase_forwarding_headers_var)