Help: Convert remaining modules to block-style comments

1 files changed, 204 insertions, 203 deletions

diff --git a/Modules/CMakePackageConfigHelpers.cmake b/Modules/CMakePackageConfigHelpers.cmake
index d5301d7379..bcc9bf85f4 100644
--- a/Modules/CMakePackageConfigHelpers.cmake
+++ b/Modules/CMakePackageConfigHelpers.cmake
@@ -1,209 +1,210 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.
 
-#.rst:
-# CMakePackageConfigHelpers
-# -------------------------
-#
-# Helpers functions for creating config files that can be included by other
-# projects to find and use a package.
-#
-# Adds the :command:`configure_package_config_file()` and
-# :command:`write_basic_package_version_file()` commands.
-#
-# Generating a Package Configuration File
-# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-#
-# .. command:: configure_package_config_file
-#
-#  Create a config file for a project::
-#
-#    configure_package_config_file(<input> <output>
-#      INSTALL_DESTINATION <path>
-#      [PATH_VARS <var1> <var2> ... <varN>]
-#      [NO_SET_AND_CHECK_MACRO]
-#      [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
-#      [INSTALL_PREFIX <path>]
-#      )
-#
-# ``configure_package_config_file()`` should be used instead of the plain
-# :command:`configure_file()` command when creating the ``<PackageName>Config.cmake``
-# or ``<PackageName>-config.cmake`` file for installing a project or library.
-# It helps making the resulting package relocatable by avoiding hardcoded paths
-# in the installed ``Config.cmake`` file.
-#
-# In a ``FooConfig.cmake`` file there may be code like this to make the install
-# destinations know to the using project:
-#
-# .. code-block:: cmake
-#
-#    set(FOO_INCLUDE_DIR   "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
-#    set(FOO_DATA_DIR   "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
-#    set(FOO_ICONS_DIR   "@CMAKE_INSTALL_PREFIX@/share/icons" )
-#    #...logic to determine installedPrefix from the own location...
-#    set(FOO_CONFIG_DIR  "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
-#
-# All 4 options shown above are not sufficient, since the first 3 hardcode the
-# absolute directory locations, and the 4th case works only if the logic to
-# determine the ``installedPrefix`` is correct, and if ``CONFIG_INSTALL_DIR``
-# contains a relative path, which in general cannot be guaranteed.  This has the
-# effect that the resulting ``FooConfig.cmake`` file would work poorly under
-# Windows and OSX, where users are used to choose the install location of a
-# binary package at install time, independent from how
-# :variable:`CMAKE_INSTALL_PREFIX` was set at build/cmake time.
-#
-# Using ``configure_package_config_file`` helps.  If used correctly, it makes
-# the resulting ``FooConfig.cmake`` file relocatable.  Usage:
-#
-# 1. write a ``FooConfig.cmake.in`` file as you are used to
-# 2. insert a line containing only the string ``@PACKAGE_INIT@``
-# 3. instead of ``set(FOO_DIR "@SOME_INSTALL_DIR@")``, use
-#    ``set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@")`` (this must be after the
-#    ``@PACKAGE_INIT@`` line)
-# 4. instead of using the normal :command:`configure_file()`, use
-#    ``configure_package_config_file()``
-#
-#
-#
-# The ``<input>`` and ``<output>`` arguments are the input and output file, the
-# same way as in :command:`configure_file()`.
-#
-# The ``<path>`` given to ``INSTALL_DESTINATION`` must be the destination where
-# the ``FooConfig.cmake`` file will be installed to.  This path can either be
-# absolute, or relative to the ``INSTALL_PREFIX`` path.
-#
-# The variables ``<var1>`` to ``<varN>`` given as ``PATH_VARS`` are the
-# variables which contain install destinations.  For each of them the macro will
-# create a helper variable ``PACKAGE_<var...>``.  These helper variables must be
-# used in the ``FooConfig.cmake.in`` file for setting the installed location.
-# They are calculated by ``configure_package_config_file`` so that they are
-# always relative to the installed location of the package.  This works both for
-# relative and also for absolute locations.  For absolute locations it works
-# only if the absolute location is a subdirectory of ``INSTALL_PREFIX``.
-#
-# If the ``INSTALL_PREFIX`` argument is passed, this is used as base path to
-# calculate all the relative paths.  The ``<path>`` argument must be an absolute
-# path.  If this argument is not passed, the :variable:`CMAKE_INSTALL_PREFIX`
-# variable will be used instead.  The default value is good when generating a
-# FooConfig.cmake file to use your package from the install tree.  When
-# generating a FooConfig.cmake file to use your package from the build tree this
-# option should be used.
-#
-# By default ``configure_package_config_file`` also generates two helper macros,
-# ``set_and_check()`` and ``check_required_components()`` into the
-# ``FooConfig.cmake`` file.
-#
-# ``set_and_check()`` should be used instead of the normal ``set()`` command for
-# setting directories and file locations.  Additionally to setting the variable
-# it also checks that the referenced file or directory actually exists and fails
-# with a ``FATAL_ERROR`` otherwise.  This makes sure that the created
-# ``FooConfig.cmake`` file does not contain wrong references.
-# When using the ``NO_SET_AND_CHECK_MACRO``, this macro is not generated
-# into the ``FooConfig.cmake`` file.
-#
-# ``check_required_components(<PackageName>)`` should be called at the end of
-# the ``FooConfig.cmake`` file. This macro checks whether all requested,
-# non-optional components have been found, and if this is not the case, sets
-# the ``Foo_FOUND`` variable to ``FALSE``, so that the package is considered to
-# be not found.  It does that by testing the ``Foo_<Component>_FOUND``
-# variables for all requested required components.  This macro should be
-# called even if the package doesn't provide any components to make sure
-# users are not specifying components erroneously.  When using the
-# ``NO_CHECK_REQUIRED_COMPONENTS_MACRO`` option, this macro is not generated
-# into the ``FooConfig.cmake`` file.
-#
-# For an example see below the documentation for
-# :command:`write_basic_package_version_file()`.
-#
-# Generating a Package Version File
-# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-#
-# .. command:: write_basic_package_version_file
-#
-#  Create a version file for a project::
-#
-#    write_basic_package_version_file(<filename>
-#      [VERSION <major.minor.patch>]
-#      COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion> )
-#
-#
-# Writes a file for use as ``<PackageName>ConfigVersion.cmake`` file to
-# ``<filename>``.  See the documentation of :command:`find_package()` for
-# details on this.
-#
-# ``<filename>`` is the output filename, it should be in the build tree.
-# ``<major.minor.patch>`` is the version number of the project to be installed.
-#
-# If no ``VERSION`` is given, the :variable:`PROJECT_VERSION` variable is used.
-# If this hasn't been set, it errors out.
-#
-# The ``COMPATIBILITY`` mode ``AnyNewerVersion`` means that the installed
-# package version will be considered compatible if it is newer or exactly the
-# same as the requested version.  This mode should be used for packages which
-# are fully backward compatible, also across major versions.
-# If ``SameMajorVersion`` is used instead, then the behaviour differs from
-# ``AnyNewerVersion`` in that the major version number must be the same as
-# requested, e.g.  version 2.0 will not be considered compatible if 1.0 is
-# requested.  This mode should be used for packages which guarantee backward
-# compatibility within the same major version.
-# If ``SameMinorVersion`` is used, the behaviour is the same as
-# ``SameMajorVersion``, but both major and minor version must be the same as
-# requested, e.g version 0.2 will not be compatible if 0.1 is requested.
-# If ``ExactVersion`` is used, then the package is only considered compatible if
-# the requested version matches exactly its own version number (not considering
-# the tweak version).  For example, version 1.2.3 of a package is only
-# considered compatible to requested version 1.2.3.  This mode is for packages
-# without compatibility guarantees.
-# If your project has more elaborated version matching rules, you will need to
-# write your own custom ``ConfigVersion.cmake`` file instead of using this
-# macro.
-#
-# Internally, this macro executes :command:`configure_file()` to create the
-# resulting version file.  Depending on the ``COMPATIBILITY``, the corresponding
-# ``BasicConfigVersion-<COMPATIBILITY>.cmake.in`` file is used.
-# Please note that these files are internal to CMake and you should not call
-# :command:`configure_file()` on them yourself, but they can be used as starting
-# point to create more sophisticted custom ``ConfigVersion.cmake`` files.
-#
-# Example Generating Package Files
-# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-#
-# Example using both :command:`configure_package_config_file` and
-# ``write_basic_package_version_file()``:
-#
-# ``CMakeLists.txt``:
-#
-# .. code-block:: cmake
-#
-#    set(INCLUDE_INSTALL_DIR include/ ... CACHE )
-#    set(LIB_INSTALL_DIR lib/ ... CACHE )
-#    set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
-#    #...
-#    include(CMakePackageConfigHelpers)
-#    configure_package_config_file(FooConfig.cmake.in
-#      ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
-#      INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
-#      PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
-#    write_basic_package_version_file(
-#      ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
-#      VERSION 1.2.3
-#      COMPATIBILITY SameMajorVersion )
-#    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
-#                  ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
-#            DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
-#
-# ``FooConfig.cmake.in``:
-#
-# ::
-#
-#    set(FOO_VERSION x.y.z)
-#    ...
-#    @PACKAGE_INIT@
-#    ...
-#    set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
-#    set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
-#
-#    check_required_components(Foo)
+#[=======================================================================[.rst:
+CMakePackageConfigHelpers
+-------------------------
+
+Helpers functions for creating config files that can be included by other
+projects to find and use a package.
+
+Adds the :command:`configure_package_config_file()` and
+:command:`write_basic_package_version_file()` commands.
+
+Generating a Package Configuration File
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. command:: configure_package_config_file
+
+ Create a config file for a project::
+
+   configure_package_config_file(<input> <output>
+     INSTALL_DESTINATION <path>
+     [PATH_VARS <var1> <var2> ... <varN>]
+     [NO_SET_AND_CHECK_MACRO]
+     [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
+     [INSTALL_PREFIX <path>]
+     )
+
+``configure_package_config_file()`` should be used instead of the plain
+:command:`configure_file()` command when creating the ``<PackageName>Config.cmake``
+or ``<PackageName>-config.cmake`` file for installing a project or library.
+It helps making the resulting package relocatable by avoiding hardcoded paths
+in the installed ``Config.cmake`` file.
+
+In a ``FooConfig.cmake`` file there may be code like this to make the install
+destinations know to the using project:
+
+.. code-block:: cmake
+
+   set(FOO_INCLUDE_DIR   "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
+   set(FOO_DATA_DIR   "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
+   set(FOO_ICONS_DIR   "@CMAKE_INSTALL_PREFIX@/share/icons" )
+   #...logic to determine installedPrefix from the own location...
+   set(FOO_CONFIG_DIR  "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
+
+All 4 options shown above are not sufficient, since the first 3 hardcode the
+absolute directory locations, and the 4th case works only if the logic to
+determine the ``installedPrefix`` is correct, and if ``CONFIG_INSTALL_DIR``
+contains a relative path, which in general cannot be guaranteed.  This has the
+effect that the resulting ``FooConfig.cmake`` file would work poorly under
+Windows and OSX, where users are used to choose the install location of a
+binary package at install time, independent from how
+:variable:`CMAKE_INSTALL_PREFIX` was set at build/cmake time.
+
+Using ``configure_package_config_file`` helps.  If used correctly, it makes
+the resulting ``FooConfig.cmake`` file relocatable.  Usage:
+
+1. write a ``FooConfig.cmake.in`` file as you are used to
+2. insert a line containing only the string ``@PACKAGE_INIT@``
+3. instead of ``set(FOO_DIR "@SOME_INSTALL_DIR@")``, use
+   ``set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@")`` (this must be after the
+   ``@PACKAGE_INIT@`` line)
+4. instead of using the normal :command:`configure_file()`, use
+   ``configure_package_config_file()``
+
+
+
+The ``<input>`` and ``<output>`` arguments are the input and output file, the
+same way as in :command:`configure_file()`.
+
+The ``<path>`` given to ``INSTALL_DESTINATION`` must be the destination where
+the ``FooConfig.cmake`` file will be installed to.  This path can either be
+absolute, or relative to the ``INSTALL_PREFIX`` path.
+
+The variables ``<var1>`` to ``<varN>`` given as ``PATH_VARS`` are the
+variables which contain install destinations.  For each of them the macro will
+create a helper variable ``PACKAGE_<var...>``.  These helper variables must be
+used in the ``FooConfig.cmake.in`` file for setting the installed location.
+They are calculated by ``configure_package_config_file`` so that they are
+always relative to the installed location of the package.  This works both for
+relative and also for absolute locations.  For absolute locations it works
+only if the absolute location is a subdirectory of ``INSTALL_PREFIX``.
+
+If the ``INSTALL_PREFIX`` argument is passed, this is used as base path to
+calculate all the relative paths.  The ``<path>`` argument must be an absolute
+path.  If this argument is not passed, the :variable:`CMAKE_INSTALL_PREFIX`
+variable will be used instead.  The default value is good when generating a
+FooConfig.cmake file to use your package from the install tree.  When
+generating a FooConfig.cmake file to use your package from the build tree this
+option should be used.
+
+By default ``configure_package_config_file`` also generates two helper macros,
+``set_and_check()`` and ``check_required_components()`` into the
+``FooConfig.cmake`` file.
+
+``set_and_check()`` should be used instead of the normal ``set()`` command for
+setting directories and file locations.  Additionally to setting the variable
+it also checks that the referenced file or directory actually exists and fails
+with a ``FATAL_ERROR`` otherwise.  This makes sure that the created
+``FooConfig.cmake`` file does not contain wrong references.
+When using the ``NO_SET_AND_CHECK_MACRO``, this macro is not generated
+into the ``FooConfig.cmake`` file.
+
+``check_required_components(<PackageName>)`` should be called at the end of
+the ``FooConfig.cmake`` file. This macro checks whether all requested,
+non-optional components have been found, and if this is not the case, sets
+the ``Foo_FOUND`` variable to ``FALSE``, so that the package is considered to
+be not found.  It does that by testing the ``Foo_<Component>_FOUND``
+variables for all requested required components.  This macro should be
+called even if the package doesn't provide any components to make sure
+users are not specifying components erroneously.  When using the
+``NO_CHECK_REQUIRED_COMPONENTS_MACRO`` option, this macro is not generated
+into the ``FooConfig.cmake`` file.
+
+For an example see below the documentation for
+:command:`write_basic_package_version_file()`.
+
+Generating a Package Version File
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. command:: write_basic_package_version_file
+
+ Create a version file for a project::
+
+   write_basic_package_version_file(<filename>
+     [VERSION <major.minor.patch>]
+     COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion> )
+
+
+Writes a file for use as ``<PackageName>ConfigVersion.cmake`` file to
+``<filename>``.  See the documentation of :command:`find_package()` for
+details on this.
+
+``<filename>`` is the output filename, it should be in the build tree.
+``<major.minor.patch>`` is the version number of the project to be installed.
+
+If no ``VERSION`` is given, the :variable:`PROJECT_VERSION` variable is used.
+If this hasn't been set, it errors out.
+
+The ``COMPATIBILITY`` mode ``AnyNewerVersion`` means that the installed
+package version will be considered compatible if it is newer or exactly the
+same as the requested version.  This mode should be used for packages which
+are fully backward compatible, also across major versions.
+If ``SameMajorVersion`` is used instead, then the behaviour differs from
+``AnyNewerVersion`` in that the major version number must be the same as
+requested, e.g.  version 2.0 will not be considered compatible if 1.0 is
+requested.  This mode should be used for packages which guarantee backward
+compatibility within the same major version.
+If ``SameMinorVersion`` is used, the behaviour is the same as
+``SameMajorVersion``, but both major and minor version must be the same as
+requested, e.g version 0.2 will not be compatible if 0.1 is requested.
+If ``ExactVersion`` is used, then the package is only considered compatible if
+the requested version matches exactly its own version number (not considering
+the tweak version).  For example, version 1.2.3 of a package is only
+considered compatible to requested version 1.2.3.  This mode is for packages
+without compatibility guarantees.
+If your project has more elaborated version matching rules, you will need to
+write your own custom ``ConfigVersion.cmake`` file instead of using this
+macro.
+
+Internally, this macro executes :command:`configure_file()` to create the
+resulting version file.  Depending on the ``COMPATIBILITY``, the corresponding
+``BasicConfigVersion-<COMPATIBILITY>.cmake.in`` file is used.
+Please note that these files are internal to CMake and you should not call
+:command:`configure_file()` on them yourself, but they can be used as starting
+point to create more sophisticted custom ``ConfigVersion.cmake`` files.
+
+Example Generating Package Files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example using both :command:`configure_package_config_file` and
+``write_basic_package_version_file()``:
+
+``CMakeLists.txt``:
+
+.. code-block:: cmake
+
+   set(INCLUDE_INSTALL_DIR include/ ... CACHE )
+   set(LIB_INSTALL_DIR lib/ ... CACHE )
+   set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
+   #...
+   include(CMakePackageConfigHelpers)
+   configure_package_config_file(FooConfig.cmake.in
+     ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
+     INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
+     PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
+   write_basic_package_version_file(
+     ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
+     VERSION 1.2.3
+     COMPATIBILITY SameMajorVersion )
+   install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
+                 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
+           DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
+
+``FooConfig.cmake.in``:
+
+::
+
+   set(FOO_VERSION x.y.z)
+   ...
+   @PACKAGE_INIT@
+   ...
+   set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
+   set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
+
+   check_required_components(Foo)
+#]=======================================================================]
 
 include(WriteBasicConfigVersionFile)