FeatureSummary: Update documentation

- Refactored and synced module documentation.
- Moved all documentation to the top header comment to make it easier to
  manage and adjust.
- Added table of contents.
- Added intro code block showing how to use this module.
- Described arguments of commands as a list.
- Used word "commands" instead of "functions".
- Added separate examples section with more examples.

Help/policy/CMP0183.rst

@@ -5,7 +5,7 @@ CMP0183
 
 :command:`add_feature_info` supports full :ref:`Condition Syntax`.
 
-The ``<enabled>`` parameter accepts a :ref:`semicolon-separated list <CMake
+The ``<condition>`` parameter accepts a :ref:`semicolon-separated list <CMake
 Language Lists>` of conditions.  CMake 3.31 and lower evaluate each
 ``condition`` as ``if(${condition})``, which does not properly handle
 conditions with nested paren groups.  CMake 4.0 and above instead prefer

Modules/FeatureSummary.cmake

@@ -7,32 +7,45 @@ include_guard(GLOBAL)
 FeatureSummary
 --------------
 
-Functions for generating a summary of enabled/disabled features.
+.. only:: html
 
-These functions can be used to generate a summary of enabled and disabled
-packages and/or features for a build tree such as::
+   .. contents::
 
-    -- The following features have been enabled:
+This module provides commands for generating a summary of enabled/disabled
+features.
 
-     * Example, usage example
+Load this module in CMake with:
 
-    -- The following OPTIONAL packages have been found:
+.. code-block:: cmake
 
-     * LibXml2 (required version >= 2.4), XML library, <http://xmlsoft.org>
-       Enables HTML-import in MyWordProcessor
-       Enables odt-export in MyWordProcessor
-     * PNG, image library, <http://www.libpng.org/pub/png/>
-       Enables saving screenshots
+  include(FeatureSummary)
 
-    -- The following OPTIONAL packages have not been found:
+Commands provided by this module can be used to generate a summary of enabled
+and disabled packages and/or features for a build tree such as::
 
-     * Lua, the Lua scripting language, <https://www.lua.org>
-       Enables macros in MyWordProcessor
-     * OpenGL, Open Graphics Library
+  -- The following features have been enabled:
+
+   * Example, usage example
+
+  -- The following OPTIONAL packages have been found:
+
+   * LibXml2 (required version >= 2.4), XML library, <http://xmlsoft.org>
+     Enables HTML-import in MyWordProcessor
+     Enables odt-export in MyWordProcessor
+   * PNG, image library, <http://www.libpng.org/pub/png/>
+     Enables saving screenshots
+
+  -- The following OPTIONAL packages have not been found:
+
+   * Lua, the Lua scripting language, <https://www.lua.org>
+     Enables macros in MyWordProcessor
+   * OpenGL, Open Graphics Library
 
 Global Properties
 ^^^^^^^^^^^^^^^^^
 
+The following global properties are used by this module:
+
 .. variable:: FeatureSummary_PKG_TYPES
 
   .. versionadded:: 3.8
@@ -69,8 +82,9 @@ Global Properties
 
   This global property defines the default package type.
 
-  When the :command:`feature_summary()` command is called, and the user has not
-  explicitly set a type of some package, its type will be set to this value.
+  When the :command:`feature_summary()` command is called, and the user has
+  not explicitly set a type of some package, its type will be set to the
+  value of this property.
 
   This value must be one of the types defined in the
   :variable:`FeatureSummary_PKG_TYPES` global property.
@@ -88,6 +102,519 @@ Global Properties
       The following <FeatureSummary_<TYPE>_DESCRIPTION> have been found:
 
   If not set, default string ``<TYPE> packages`` is used.
+
+Commands
+^^^^^^^^
+
+This module provides the following commands:
+
+* :command:`feature_summary`
+* :command:`set_package_properties`
+* :command:`add_feature_info`
+
+Printing Feature Summary
+""""""""""""""""""""""""
+
+.. command:: feature_summary
+
+  Prints information about enabled or disabled packages and features of a
+  project:
+
+  .. code-block:: cmake
+
+    feature_summary(
+      WHAT (ALL
+        | PACKAGES_FOUND | PACKAGES_NOT_FOUND
+        | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
+        | ENABLED_FEATURES | DISABLED_FEATURES)
+      [FILENAME <file>]
+      [APPEND]
+      [VAR <variable-name>]
+      [INCLUDE_QUIET_PACKAGES]
+      [FATAL_ON_MISSING_REQUIRED_PACKAGES]
+      [DESCRIPTION <description> | DEFAULT_DESCRIPTION]
+      [QUIET_ON_EMPTY]
+    )
+
+  This command can be used to print information about enabled or disabled
+  packages and features of a project.  By default, only the names of the
+  features/packages will be printed and their required version when one was
+  specified.  Use :command:`set_package_properties()` to add more useful
+  information, e.g., a homepage URL for the respective package or their
+  purpose in the project.
+
+  .. rubric:: The arguments are:
+
+  ``WHAT``
+    This is the only mandatory option.  It specifies what information will be
+    printed:
+
+    ``ALL``
+      Print everything.
+    ``ENABLED_FEATURES``
+      The list of all features which are enabled.
+    ``DISABLED_FEATURES``
+      The list of all features which are disabled.
+    ``PACKAGES_FOUND``
+      The list of all packages which have been found.
+    ``PACKAGES_NOT_FOUND``
+      The list of all packages which have not been found.
+
+    For each package type ``<TYPE>`` defined by the
+    :variable:`FeatureSummary_PKG_TYPES` global property, the following
+    information can also be used:
+
+    ``<TYPE>_PACKAGES_FOUND``
+      The list of only packages of type ``<TYPE>`` which have been found.
+    ``<TYPE>_PACKAGES_NOT_FOUND``
+      The list of only packages of type ``<TYPE>`` which have not been found.
+
+    .. versionchanged:: 3.1
+      The ``WHAT`` option is now a multi-value keyword, so that these values can
+      be combined, with the exception of the ``ALL`` value, in order to
+      customize the output.  For example:
+
+    .. code-block:: cmake
+
+      feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
+
+  ``FILENAME <file>``
+    If this option is given, the information is printed into this file instead
+    of the terminal.  Relative ``<file>`` path is interpreted as being relative
+    to the current source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).
+
+  ``APPEND``
+    If this option is given, the output is appended to the ``<file>`` provided
+    by the ``FILENAME`` option, otherwise the file is overwritten if it already
+    exists.
+
+  ``VAR <variable-name>``
+    If this option is given, the information is stored into the specified
+    variable ``<variable-name>`` instead of the terminal.
+
+  ``INCLUDE_QUIET_PACKAGES``
+    If this option is given, packages which have been searched with
+    :command:`find_package(... QUIET)` will also be listed.  By default they are
+    skipped.
+
+  ``FATAL_ON_MISSING_REQUIRED_PACKAGES``
+    If this option is given, CMake will abort with fatal error if a package
+    which is marked as one of the package types listed in the
+    :variable:`FeatureSummary_REQUIRED_PKG_TYPES` global property has not been
+    found.
+
+  ``DESCRIPTION <description>``
+    A description or headline which will be printed above the actual content.
+    Without this option, if only one package type was requested, no title is
+    printed, unless a custom string is explicitly set using this option or
+    ``DEFAULT_DESCRIPTION`` option is used that outputs a default title for the
+    requested type.
+
+  ``DEFAULT_DESCRIPTION``
+    .. versionadded:: 3.9
+
+    The default description or headline to be printed above the content as
+    opposed to the customizable ``DESCRIPTION <description>``.
+
+  ``QUIET_ON_EMPTY``
+    .. versionadded:: 3.8
+
+    If this option is given, when only one package type was requested, and no
+    packages belonging to that category were found, then no output (including
+    the ``DESCRIPTION``) is printed nor added to the ``FILENAME``, or the
+    ``VAR`` variable.
+
+Package Properties
+""""""""""""""""""
+
+.. command:: set_package_properties
+
+  Sets package properties:
+
+  .. code-block:: cmake
+
+    set_package_properties(
+      <PackageName>
+      PROPERTIES
+        [URL <url>]
+        [DESCRIPTION <description>]
+        [TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)]
+        [PURPOSE <purpose>]
+    )
+
+  Use this command to configure and provide information about the package
+  named ``<PackageName>``, which can then be displayed using the
+  :command:`feature_summary()` command.  This command can be called either
+  directly within the corresponding :ref:`Find module <Find Modules>` or in
+  the project that uses the module after invoking the :command:`find_package()`
+  call.  The features for which information can be set are determined
+  automatically after the :command:`find_package()` command.
+
+  .. rubric:: The arguments are:
+
+  ``<PackageName>``
+    The name of the package.  For example, as specified in the
+    :command:`find_package(<PackageName>)` argument.
+
+  ``PROPERTIES``
+    Specifies the properties to set:
+
+    ``URL <url>``
+      This should be the homepage of the package, or something similar.
+      Ideally this is set already directly in the
+      :ref:`Find module <Find Modules>`.
+
+    ``DESCRIPTION <description>``
+      A short description what that package is, at most one sentence.
+      Ideally this is set already directly in the
+      :ref:`Find module <Find Modules>`.
+
+    ``TYPE <type>``
+      What type of dependency has the using project on that package.
+
+      Default ``<type>`` is ``OPTIONAL``.  In this case it is a package
+      which can be used by the project when available at buildtime, but the
+      project also works without it.
+
+      ``RECOMMENDED`` package type is similar to ``OPTIONAL``, i.e.  the
+      project will build if the package is not present, but the
+      functionality of the resulting binaries will be severely limited.  If
+      a ``REQUIRED`` package is not available at buildtime, the project may
+      not even build. This can be combined with the
+      :command:`feature_summary(FATAL_ON_MISSING_REQUIRED_PACKAGES)` command
+      option.
+
+      Last, a ``RUNTIME`` package is a package which is actually not used
+      at all during the build, but which is required for actually running
+      the resulting binaries.  So if such a package is missing, the project
+      can still be built, but it may not work later on.
+
+      If ``set_package_properties()`` is called multiple times for the same
+      package with different TYPEs, the ``TYPE`` is only changed to higher
+      TYPEs (``RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED``), lower TYPEs
+      are ignored.  The ``TYPE`` property is project-specific, so it cannot
+      be set by the :ref:`Find module <Find Modules>`, but must be set in
+      the project.
+
+      The accepted types can be changed by setting the
+      :variable:`FeatureSummary_PKG_TYPES` global property.
+
+    ``PURPOSE <purpose>``
+      This describes which features this package enables in the project,
+      i.e.  it tells the user what functionality they get in the resulting
+      binaries.  If ``set_package_properties()`` is called multiple times
+      for a package, all ``PURPOSE`` properties are appended to a list of
+      purposes of the package in the project.  As the ``TYPE`` property,
+      also the ``PURPOSE`` property is project-specific, so it cannot be
+      set by the :ref:`Find module <Find Modules>`, but must be set in the
+      project.
+
+Adding Feature Info
+"""""""""""""""""""
+
+.. command:: add_feature_info
+
+  Adds feature information:
+
+  .. code-block:: cmake
+
+    add_feature_info(<name> <condition> <description>)
+
+  Use this command to add information about a feature identified with a given
+  ``<name>``.
+
+  .. rubric:: The arguments are:
+
+  ``<name>``
+    Identification name for a feature being added.
+
+  ``<condition>``
+    Specifies the conditions that determine whether this feature is enabled
+    or disabled.
+
+    The ``<condition>`` argument can be:
+
+    * A single condition (such as a variable name).
+
+    * .. versionadded:: 3.8
+        A :ref:`semicolon-separated list <CMake Language Lists>` of multiple
+        conditions.
+
+    * .. versionadded:: 4.0
+        A full :ref:`Condition Syntax` as used in an ``if(<condition>)``
+        clause.  See policy :policy:`CMP0183`.  This enables using entire
+        condition syntax (such as grouping conditions with parens and
+        similar).
+
+  ``<description>``
+    A text describing the feature.  This information can be displayed using
+    :command:`feature_summary()` for ``ENABLED_FEATURES`` and
+    ``DISABLED_FEATURES`` respectively.
+
+Deprecated Commands
+"""""""""""""""""""
+
+The following legacy and deprecated commands are provided for backward
+compatibility with previous CMake versions:
+
+.. command:: set_package_info
+
+  .. deprecated:: 3.8
+    Use the :command:`set_package_properties`, and :command:`add_feature_info`
+    commands instead.
+
+  Sets up information about the specified package, which can then be displayed
+  via :command:`feature_summary()`:
+
+  .. code-block:: cmake
+
+    set_package_info(<PackageName> <description> [<url> [<purpose>]])
+
+  ``<PackageName>``
+    Name of the package.
+
+  ``<description>``
+    A short description of the package.
+
+  ``<url>``
+    Homepage of the package.
+
+  ``<purpose>``
+    The purpose of the package.
+
+  This command can be used either directly in the
+  :ref:`Find module <Find Modules>` or in the project which uses the
+  ``FeatureSummary`` module after the :command:`find_package()` call.  The
+  features for which information can be set are added automatically by the
+  ``find_package()`` command.
+
+.. command:: set_feature_info
+
+  .. deprecated:: 3.8
+
+  Sets feature info for a package:
+
+  .. code-block:: cmake
+
+    set_feature_info(<name> <description> [<url>])
+
+  Does the same as:
+
+  .. code-block:: cmake
+
+    set_package_info(<name> <description> [<url>])
+
+.. command:: print_enabled_features
+
+  .. deprecated:: 3.8
+
+  Prints enabled features:
+
+  .. code-block:: cmake
+
+    print_enabled_features()
+
+  Does the same as:
+
+  .. code-block:: cmake
+
+    feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
+
+.. command:: print_disabled_features
+
+  .. deprecated:: 3.8
+
+  Prints disabled features:
+
+  .. code-block:: cmake
+
+    print_disabled_features()
+
+  Does the same as:
+
+  .. code-block:: cmake
+
+    feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
+
+Examples
+^^^^^^^^
+
+Example: Appending Feature Summary to a File
+""""""""""""""""""""""""""""""""""""""""""""
+
+In the following example, the feature summary output will be appended to
+a specified file instead of printing:
+
+.. code-block:: cmake
+
+  include(FeatureSummary)
+  feature_summary(WHAT ALL FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
+
+Example: Storing Feature Summary in a Variable
+""""""""""""""""""""""""""""""""""""""""""""""
+
+In the following example, the feature summary of enabled features is stored
+in a specified variable ``enabledFeaturesText``, including the ``QUIET``
+packages:
+
+.. code-block:: cmake
+
+  include(FeatureSummary)
+
+  feature_summary(
+    WHAT ENABLED_FEATURES
+    INCLUDE_QUIET_PACKAGES
+    DESCRIPTION "Enabled Features:"
+    VAR enabledFeaturesText
+  )
+
+  message(STATUS "${enabledFeaturesText}")
+
+Example: Adding a Custom Package Type
+"""""""""""""""""""""""""""""""""""""
+
+In the following example a custom package type is added and printed only
+the categories that are not empty:
+
+.. code-block:: cmake
+
+  include(FeatureSummary)
+
+  set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
+
+  find_package(FOO)
+  set_package_properties(FOO PROPERTIES TYPE BUILD)
+
+  feature_summary(
+    WHAT BUILD_PACKAGES_FOUND
+    DESCRIPTION "Build tools found:"
+    QUIET_ON_EMPTY
+  )
+
+  feature_summary(
+    WHAT BUILD_PACKAGES_NOT_FOUND
+    DESCRIPTION "Build tools not found:"
+    QUIET_ON_EMPTY
+  )
+
+Example: Setting Package Info
+"""""""""""""""""""""""""""""
+
+Example for setting the info for a package:
+
+.. code-block:: cmake
+
+  include(FeatureSummary)
+
+  find_package(LibXml2)
+  set_package_properties(
+    LibXml2
+    PROPERTIES
+      DESCRIPTION "XML library"
+      URL "http://xmlsoft.org"
+  )
+  # or
+  set_package_properties(
+    LibXml2
+    PROPERTIES
+      TYPE RECOMMENDED
+      PURPOSE "Enables HTML-import in MyWordProcessor"
+  )
+  # or
+  set_package_properties(
+    LibXml2
+    PROPERTIES
+      TYPE OPTIONAL
+      PURPOSE "Enables odt-export in MyWordProcessor"
+  )
+
+  find_package(DBUS)
+  set_package_properties(
+    DBUS
+    PROPERTIES
+      TYPE RUNTIME
+      PURPOSE "Necessary to disable the screensaver during a presentation"
+  )
+
+Example: Printing Feature Summary
+"""""""""""""""""""""""""""""""""
+
+In the following example, this module is used to output feature summary at
+the end of the configuration.  If any required package is not found,
+processing stops with an error message at the end of the configuration
+phase.
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.15)
+  project(Example)
+
+  add_library(example example.c)
+
+  include(FeatureSummary)
+
+  find_package(CURL)
+  set_package_properties(CURL PROPERTIES TYPE REQUIRED)
+  target_link_libraries(example PRIVATE CURL::libcurl)
+
+  find_package(LibXml2 QUIET)
+  set_package_properties(LibXml2 PROPERTIES TYPE RECOMMENDED)
+  if(LibXml2_FOUND)
+    target_link_libraries(example PRIVATE LibXml2::LibXml2)
+  endif()
+
+  feature_summary(
+    WHAT ALL
+    INCLUDE_QUIET_PACKAGES
+    DESCRIPTION "Feature summary:"
+    FATAL_ON_MISSING_REQUIRED_PACKAGES
+  )
+
+Examples: Setting Feature Info
+""""""""""""""""""""""""""""""
+
+Example for setting the info for a feature:
+
+.. code-block:: cmake
+
+  include(FeatureSummary)
+
+  option(WITH_FOO "Help for foo" ON)
+
+  add_feature_info(Foo WITH_FOO "this feature provides very cool stuff")
+
+Example for setting feature info based on a list of conditions:
+
+.. code-block:: cmake
+
+  include(FeatureSummary)
+
+  option(WITH_FOO "Help for foo" ON)
+  option(WITH_BAR "Help for bar" OFF)
+
+  add_feature_info(
+    FooBar
+    "WITH_FOO;NOT WITH_BAR"
+    "this feature is enabled when WITH_FOO is ON and WITH_BAR turned OFF"
+  )
+
+In the next example feature info are set depending on a full condition
+syntax.  Unlike semicolon-separated list of conditions, this enables using
+entire condition syntax as being the ``if`` clause argument:
+
+.. code-block:: cmake
+
+  include(FeatureSummary)
+
+  option(WITH_FOO "Help for foo" ON)
+  option(WITH_BAR "Help for bar" ON)
+  option(WITH_BAZ "Help for baz" OFF)
+
+  add_feature_info(
+    FooBarBaz
+    "WITH_FOO AND (WITH_BAR OR WITH_BAZ)"
+    "this feature is enabled when the entire condition is true"
+  )
 #]=======================================================================]
 
 get_property(_fsPkgTypeIsSet GLOBAL PROPERTY FeatureSummary_PKG_TYPES SET)
@@ -105,15 +632,7 @@ if(NOT _fsDefaultPkgTypeIsSet)
   set_property(GLOBAL PROPERTY FeatureSummary_DEFAULT_PKG_TYPE OPTIONAL)
 endif()
 
-#[=======================================================================[.rst:
-
-Functions
-^^^^^^^^^
-
-#]=======================================================================]
-
 function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet)
-
   get_property(_fsPkgTypes GLOBAL PROPERTY FeatureSummary_PKG_TYPES)
   get_property(_fsDefaultPkgType GLOBAL PROPERTY FeatureSummary_DEFAULT_PKG_TYPE)
 
@@ -208,155 +727,6 @@ function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet)
   set(${_var} "${_currentFeatureText}" PARENT_SCOPE)
 endfunction()
 
-
-#[=======================================================================[.rst:
-.. command:: feature_summary
-
-  .. code-block:: cmake
-
-    feature_summary([FILENAME <file>]
-                    [APPEND]
-                    [VAR <variable_name>]
-                    [INCLUDE_QUIET_PACKAGES]
-                    [FATAL_ON_MISSING_REQUIRED_PACKAGES]
-                    [DESCRIPTION <description> | DEFAULT_DESCRIPTION]
-                    [QUIET_ON_EMPTY]
-                    WHAT (ALL
-                         | PACKAGES_FOUND | PACKAGES_NOT_FOUND
-                         | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
-                         | ENABLED_FEATURES | DISABLED_FEATURES)
-                   )
-
-  This function can be used to print information about
-  enabled or disabled packages and features of a project.  By default,
-  only the names of the features/packages will be printed and their
-  required version when one was specified.  Use
-  :command:`set_package_properties()` to add more useful information, like e.g.
-  a homepage URL for the respective package or their purpose in the project.
-
-  The options are:
-
-  ``WHAT``
-    This is the only mandatory option.  It specifies what information will be
-    printed:
-
-    ``ALL``
-      Print everything.
-    ``ENABLED_FEATURES``
-      The list of all features which are enabled.
-    ``DISABLED_FEATURES``
-      The list of all features which are disabled.
-    ``PACKAGES_FOUND``
-      The list of all packages which have been found.
-    ``PACKAGES_NOT_FOUND``
-      The list of all packages which have not been found.
-
-    For each package type ``<TYPE>`` defined by the
-    :variable:`FeatureSummary_PKG_TYPES` global property, the following
-    information can also be used:
-
-    ``<TYPE>_PACKAGES_FOUND``
-      The list of only packages of type ``<TYPE>`` which have been found.
-    ``<TYPE>_PACKAGES_NOT_FOUND``
-      The list of only packages of type ``<TYPE>`` which have not been found.
-
-    .. versionchanged:: 3.1
-      The ``WHAT`` option is now a multi-value keyword, so that these values can
-      be combined, with the exception of the ``ALL`` value, in order to
-      customize the output.  For example:
-
-    .. code-block:: cmake
-
-      feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
-
-  ``FILENAME <file>``
-    If this option is given, the information is printed into this file instead
-    of the terminal.  Relative ``<file>`` path is interpreted as being relative
-    to the current source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).
-
-  ``APPEND``
-    If this option is given, the output is appended to the ``<file>`` provided
-    by the ``FILENAME`` option, otherwise the file is overwritten if it already
-    exists.
-
-  ``VAR <variable_name>``
-    If this option is given, the information is stored into the specified
-    variable ``<variable_name>`` instead of the terminal.
-
-  ``DESCRIPTION <description>``
-    A description or headline which will be printed above the actual content.
-    Without this option, if only one package type was requested, no title is
-    printed, unless a custom string is explicitly set using this option or
-    ``DEFAULT_DESCRIPTION`` option is used that outputs a default title for the
-    requested type.
-
-  ``DEFAULT_DESCRIPTION``
-    .. versionadded:: 3.9
-
-    The default description or headline to be printed above the content as
-    opposed to the customizable ``DESCRIPTION <description>``.
-
-  ``INCLUDE_QUIET_PACKAGES``
-    If this option is given, packages which have been searched with
-    :command:`find_package(... QUIET)` will also be listed.  By default they are
-    skipped.
-
-  ``FATAL_ON_MISSING_REQUIRED_PACKAGES``
-    If this option is given, CMake will abort with fatal error if a package
-    which is marked as one of the package types listed in the
-    :variable:`FeatureSummary_REQUIRED_PKG_TYPES` global property has not been
-    found.
-
-  The :variable:`FeatureSummary_DEFAULT_PKG_TYPE` global property can be
-  modified to change the default package type assigned when not explicitly
-  assigned by the user.
-
-  ``QUIET_ON_EMPTY``
-    .. versionadded:: 3.8
-
-    If this option is given, when only one package type was requested, and no
-    packages belonging to that category were found, then no output (including
-    the ``DESCRIPTION``) is printed nor added to the ``FILENAME``, or the
-    ``VAR`` variable.
-
-  Example 1, append everything to a file:
-
-  .. code-block:: cmake
-
-   include(FeatureSummary)
-   feature_summary(WHAT ALL
-                   FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
-
-  Example 2, print the enabled features into the variable
-  ``enabledFeaturesText``, including the ``QUIET`` packages:
-
-  .. code-block:: cmake
-
-    include(FeatureSummary)
-    feature_summary(WHAT ENABLED_FEATURES
-                   INCLUDE_QUIET_PACKAGES
-                   DESCRIPTION "Enabled Features:"
-                   VAR enabledFeaturesText)
-    message(STATUS "${enabledFeaturesText}")
-
-  Example 3, add custom package type and print only the categories that are not
-  empty:
-
-  .. code-block:: cmake
-
-    include(FeatureSummary)
-    set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
-    find_package(FOO)
-    set_package_properties(FOO PROPERTIES TYPE BUILD)
-    feature_summary(WHAT BUILD_PACKAGES_FOUND
-                    DESCRIPTION "Build tools found:"
-                    QUIET_ON_EMPTY)
-    feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
-                    DESCRIPTION "Build tools not found:"
-                    QUIET_ON_EMPTY)
-
-#]=======================================================================]
-
 function(FEATURE_SUMMARY)
 # cmake_parse_arguments(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
   set(options APPEND
@@ -498,93 +868,8 @@ function(FEATURE_SUMMARY)
   if(requiredPackagesNotFound  AND  _FS_FATAL_ON_MISSING_REQUIRED_PACKAGES)
     message(FATAL_ERROR "feature_summary() Error: REQUIRED package(s) are missing, aborting CMake run.")
   endif()
-
 endfunction()
 
-#[=======================================================================[.rst:
-.. command:: set_package_properties
-
-  .. code-block:: cmake
-
-    set_package_properties(<name> PROPERTIES
-                           [URL <url>]
-                           [DESCRIPTION <description>]
-                           [TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)]
-                           [PURPOSE <purpose>]
-                          )
-
-  Use this function to configure and provide information about the package named
-  ``<name>``, which can then be displayed using the
-  :command:`feature_summary()` command.  This can be performed either directly
-  within the corresponding :ref:`Find module <Find Modules>` or in the project
-  that uses the module after invoking the :command:`find_package()` call.  The
-  features for which information can be set are determined automatically after
-  the :command:`find_package()` command.
-
-  ``URL <url>``
-    This should be the homepage of the package, or something similar.
-    Ideally this is set already directly in the
-    :ref:`Find module <Find Modules>`.
-
-  ``DESCRIPTION <description>``
-    A short description what that package is, at most one sentence.
-    Ideally this is set already directly in the
-    :ref:`Find module <Find Modules>`.
-
-  ``TYPE <type>``
-    What type of dependency has the using project on that package.
-    Default is ``OPTIONAL``.  In this case it is a package which can be used
-    by the project when available at buildtime, but it also work without.
-    ``RECOMMENDED`` is similar to ``OPTIONAL``, i.e.  the project will build if
-    the package is not present, but the functionality of the resulting
-    binaries will be severely limited.  If a ``REQUIRED`` package is not
-    available at buildtime, the project may not even build.  This can be
-    combined with the
-    :command:`feature_summary(FATAL_ON_MISSING_REQUIRED_PACKAGES)` command
-    option.  Last, a ``RUNTIME`` package is a package which is actually not used
-    at all during the build, but which is required for actually running the
-    resulting binaries.  So if such a package is
-    missing, the project can still be built, but it may not work later on.
-    If ``set_package_properties()`` is called multiple times for the same
-    package with different TYPEs, the ``TYPE`` is only changed to higher
-    TYPEs (``RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED``), lower TYPEs are
-    ignored.  The ``TYPE`` property is project-specific, so it cannot be set
-    by the :ref:`Find module <Find Modules>`, but must be set in the project.
-    The accepted types can be changed by setting the
-    :variable:`FeatureSummary_PKG_TYPES` global property.
-
-  ``PURPOSE <purpose>``
-    This describes which features this package enables in the
-    project, i.e.  it tells the user what functionality they get in the
-    resulting binaries.  If ``set_package_properties()`` is called multiple
-    times for a package, all ``PURPOSE`` properties are appended to a list of
-    purposes of the package in the project.  As the ``TYPE`` property, also
-    the ``PURPOSE`` property is project-specific, so it cannot be set by the
-    :ref:`Find module <Find Modules>`, but must be set in the project.
-
-  Example for setting the info for a package:
-
-  .. code-block:: cmake
-
-    include(FeatureSummary)
-    find_package(LibXml2)
-    set_package_properties(LibXml2 PROPERTIES
-                           DESCRIPTION "XML library"
-                           URL "http://xmlsoft.org")
-    # or
-    set_package_properties(LibXml2 PROPERTIES
-                           TYPE RECOMMENDED
-                           PURPOSE "Enables HTML-import in MyWordProcessor")
-    # or
-    set_package_properties(LibXml2 PROPERTIES
-                           TYPE OPTIONAL
-                           PURPOSE "Enables odt-export in MyWordProcessor")
-
-    find_package(DBUS)
-    set_package_properties(DBUS PROPERTIES
-      TYPE RUNTIME
-      PURPOSE "Necessary to disable the screensaver during a presentation")
-#]=======================================================================]
 function(SET_PACKAGE_PROPERTIES _name _props)
   if(NOT "${_props}" STREQUAL "PROPERTIES")
     message(FATAL_ERROR "PROPERTIES keyword is missing in SET_PACKAGE_PROPERTIES() call.")
@@ -609,7 +894,6 @@ function(SET_PACKAGE_PROPERTIES _name _props)
     set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_SPP_DESCRIPTION}" )
   endif()
 
-
   if(_SPP_URL)
     get_property(_info  GLOBAL PROPERTY _CMAKE_${_name}_URL)
     if(_info AND NOT "${_info}" STREQUAL "${_SPP_URL}")
@@ -619,7 +903,6 @@ function(SET_PACKAGE_PROPERTIES _name _props)
     set_property(GLOBAL PROPERTY _CMAKE_${_name}_URL "${_SPP_URL}" )
   endif()
 
-
   # handle the PURPOSE: use APPEND, since there can be multiple purposes for one package inside a project
   if(_SPP_PURPOSE)
     set_property(GLOBAL APPEND PROPERTY _CMAKE_${_name}_PURPOSE "${_SPP_PURPOSE}" )
@@ -648,68 +931,8 @@ function(SET_PACKAGE_PROPERTIES _name _props)
       set_property(GLOBAL PROPERTY _CMAKE_${_name}_TYPE "${_SPP_TYPE}" )
     endif()
   endif()
-
 endfunction()
 
-#[=======================================================================[.rst:
-.. command:: add_feature_info
-
-  .. code-block:: cmake
-
-    add_feature_info(<name> <enabled> <description>)
-
-  Use this function to add information about a feature identified with a given
-  ``<name>``.  The ``<enabled>`` contains whether this feature is enabled or
-  not.  It can be a variable or a list of conditions.
-  ``<description>`` is a text describing the feature.  The information can
-  be displayed using :command:`feature_summary()` for ``ENABLED_FEATURES`` and
-  ``DISABLED_FEATURES`` respectively.
-
-  .. versionchanged:: 3.8
-    ``<enabled>`` can be a list of conditions.
-
-  .. versionchanged:: 4.0
-    Full :ref:`Condition Syntax` is now supported for ``<enabled>``.
-    See policy :policy:`CMP0183`.
-
-  Example for setting the info for a feature:
-
-  .. code-block:: cmake
-
-    include(FeatureSummary)
-
-    option(WITH_FOO "Help for foo" ON)
-    add_feature_info(Foo WITH_FOO "this feature provides very cool stuff")
-
-  Example for setting feature info based on a list of conditions:
-
-  .. code-block:: cmake
-
-    option(WITH_FOO "Help for foo" ON)
-    option(WITH_BAR "Help for bar" OFF)
-    add_feature_info(
-      FooBar
-      "WITH_FOO;NOT WITH_BAR"
-      "this feature is enabled when WITH_FOO is ON and WITH_BAR turned OFF"
-    )
-
-  Example for setting feature info depending on a full condition syntax:
-
-  Unlike semicolon-separated list of conditions, this enables using entire
-  condition syntax as being the ``if`` clause argument, such as grouping
-  conditions with parens and similar.
-
-  .. code-block:: cmake
-
-    option(WITH_FOO "Help for foo" ON)
-    option(WITH_BAR "Help for bar" ON)
-    option(WITH_BAZ "Help for baz" OFF)
-    add_feature_info(
-      FooBarBaz
-      "WITH_FOO AND (WITH_BAR OR WITH_BAZ)"
-      "this feature is enabled when the entire condition is true"
-    )
-#]=======================================================================]
 function(ADD_FEATURE_INFO _name _depends _desc)
   cmake_policy(GET CMP0183 _CDO_CMP0183
     PARENT_SCOPE # undocumented, do not use outside of CMake
@@ -749,34 +972,8 @@ function(ADD_FEATURE_INFO _name _depends _desc)
   unset(_CDO_CMP0183)
 endfunction()
 
-
 # The stuff below is only kept for compatibility
 
-#[=======================================================================[.rst:
-Deprecated Functions
-^^^^^^^^^^^^^^^^^^^^
-
-The following legacy and deprecated functions are provided for backward
-compatibility with previous CMake versions:
-
-.. command:: set_package_info
-
-  .. deprecated:: 3.8
-
-  .. code-block:: cmake
-
-    set_package_info(<name> <description> [ <url> [<purpose>] ])
-
-  Set up information about the package ``<name>``, which can then be displayed
-  via :command:`feature_summary()`.  This can be done either directly in the
-  :ref:`Find module <Find Modules>` or in the project which uses the
-  ``FeatureSummary`` module after the :command:`find_package()` call.  The
-  features for which information can be set are added automatically by the
-  ``find_package()`` command.
-
-  This function is deprecated.  Use the :command:`set_package_properties()`, and
-  :command:`add_feature_info()` functions instead.
-#]=======================================================================]
 function(SET_PACKAGE_INFO _name _desc)
   message(DEPRECATION "SET_PACKAGE_INFO is deprecated. Use SET_PACKAGE_PROPERTIES instead.")
   unset(_url)
@@ -796,62 +993,17 @@ function(SET_PACKAGE_INFO _name _desc)
   endif()
 endfunction()
 
-#[=======================================================================[.rst:
-.. command:: set_feature_info
-
-  .. deprecated:: 3.8
-
-  .. code-block:: cmake
-
-    set_feature_info(<name> <description> [<url>])
-
-  Does the same as:
-
-  .. code-block:: cmake
-
-    set_package_info(<name> <description> [<url>])
-#]=======================================================================]
 function(SET_FEATURE_INFO)
   message(DEPRECATION "SET_FEATURE_INFO is deprecated. Use ADD_FEATURE_INFO instead.")
   set_package_info(${ARGN})
 endfunction()
 
-#[=======================================================================[.rst:
-.. command:: print_enabled_features
-
-  .. deprecated:: 3.8
-
-  .. code-block:: cmake
-
-    print_enabled_features()
-
-  Does the same as:
-
-  .. code-block:: cmake
-
-    feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
-#]=======================================================================]
 function(PRINT_ENABLED_FEATURES)
   message(DEPRECATION "PRINT_ENABLED_FEATURES is deprecated. Use
     feature_summary(WHAT ENABLED_FEATURES DESCRIPTION \"Enabled features:\")")
   feature_summary(WHAT ENABLED_FEATURES  DESCRIPTION "Enabled features:")
 endfunction()
 
-#[=======================================================================[.rst:
-.. command:: print_disabled_features
-
-  .. deprecated:: 3.8
-
-  .. code-block:: cmake
-
-    print_disabled_features()
-
-  Does the same as:
-
-  .. code-block:: cmake
-
-    feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
-#]=======================================================================]
 function(PRINT_DISABLED_FEATURES)
   message(DEPRECATION "PRINT_DISABLED_FEATURES is deprecated. Use
     feature_summary(WHAT DISABLED_FEATURES DESCRIPTION \"Disabled features:\")")