Merge topic 'doc-FeatureSummary'

7aa97b94 FeatureSummary: Add include() to examples
46ded385 FeatureSummary: Format documentation
5d17e995 FeatureSummary: Convert docs to a bracket comment
7c92c843 FeatureSummary: Order function implementations the same as the documentation

1 files changed, 335 insertions, 342 deletions

diff --git a/Modules/FeatureSummary.cmake b/Modules/FeatureSummary.cmake
index 764a5f7..548d12a 100644
--- a/Modules/FeatureSummary.cmake
+++ b/Modules/FeatureSummary.cmake
@@ -1,268 +1,27 @@
-#.rst:
-# FeatureSummary
-# --------------
-#
-# Macros for generating a summary of enabled/disabled features
-#
-#
-#
-# This module provides the macros feature_summary(),
-# set_package_properties() and add_feature_info().  For compatibility it
-# also still provides set_package_info(), set_feature_info(),
-# print_enabled_features() and print_disabled_features().
-#
-# These macros can be used to generate a summary of enabled and disabled
-# packages and/or feature for a build tree:
-#
-# ::
-#
-#     -- The following OPTIONAL packages have been found:
-#     LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
-#        * Enables HTML-import in MyWordProcessor
-#        * Enables odt-export in MyWordProcessor
-#     PNG , A PNG image library. , <http://www.libpng.org/pub/png/>
-#        * Enables saving screenshots
-#     -- The following OPTIONAL packages have not been found:
-#     Lua51 , The Lua scripting language. , <http://www.lua.org>
-#        * Enables macros in MyWordProcessor
-#     Foo , Foo provides cool stuff.
-#
-#
-#
-#
-#
-# ::
-#
-#     FEATURE_SUMMARY( [FILENAME <file>]
-#                      [APPEND]
-#                      [VAR <variable_name>]
-#                      [INCLUDE_QUIET_PACKAGES]
-#                      [FATAL_ON_MISSING_REQUIRED_PACKAGES]
-#                      [DESCRIPTION "Found packages:"]
-#                      WHAT (ALL | PACKAGES_FOUND | PACKAGES_NOT_FOUND
-#                           | ENABLED_FEATURES | DISABLED_FEATURES)
-#                    )
-#
-#
-#
-# The FEATURE_SUMMARY() macro can be used to print information about
-# enabled or disabled packages or 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 SET_PACKAGE_PROPERTIES()
-# to add more useful information, like e.g.  a download URL for the
-# respective package or their purpose in the project.
-#
-# The WHAT option is the only mandatory option.  Here you specify 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
-# ``OPTIONAL_PACKAGES_FOUND``
-#  only those packages which have been found which have the type OPTIONAL
-# ``OPTIONAL_PACKAGES_NOT_FOUND``
-#  only those packages which have not been found which have the type OPTIONAL
-# ``RECOMMENDED_PACKAGES_FOUND``
-#  only those packages which have been found which have the type RECOMMENDED
-# ``RECOMMENDED_PACKAGES_NOT_FOUND``
-#  only those packages which have not been found which have the type RECOMMENDED
-# ``REQUIRED_PACKAGES_FOUND``
-#  only those packages which have been found which have the type REQUIRED
-# ``REQUIRED_PACKAGES_NOT_FOUND``
-#  only those packages which have not been found which have the type REQUIRED
-# ``RUNTIME_PACKAGES_FOUND``
-#  only those packages which have been found which have the type RUNTIME
-# ``RUNTIME_PACKAGES_NOT_FOUND``
-#  only those packages which have not been found which have the type RUNTIME
-#
-# With the exception of the ``ALL`` value, these values can be combined
-# in order to customize the output. For example:
-#
-# ::
-#
-#    feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
-#
-#
-#
-# If a FILENAME is given, the information is printed into this file.  If
-# APPEND is used, it is appended to this file, otherwise the file is
-# overwritten if it already existed.  If the VAR option is used, the
-# information is "printed" into the specified variable.  If FILENAME is
-# not used, the information is printed to the terminal.  Using the
-# DESCRIPTION option a description or headline can be set which will be
-# printed above the actual content.  If INCLUDE_QUIET_PACKAGES is given,
-# packages which have been searched with find_package(...  QUIET) will
-# also be listed.  By default they are skipped.  If
-# FATAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if a
-# package which is marked as REQUIRED has not been found.
-#
-# Example 1, append everything to a file:
-#
-# ::
-#
-#    feature_summary(WHAT ALL
-#                    FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
-#
-#
-#
-# Example 2, print the enabled features into the variable
-# enabledFeaturesText, including QUIET packages:
-#
-# ::
-#
-#    feature_summary(WHAT ENABLED_FEATURES
-#                    INCLUDE_QUIET_PACKAGES
-#                    DESCRIPTION "Enabled Features:"
-#                    VAR enabledFeaturesText)
-#    message(STATUS "${enabledFeaturesText}")
-#
-#
-#
-#
-#
-# ::
-#
-#     SET_PACKAGE_PROPERTIES(<name> PROPERTIES
-#                            [ URL <url> ]
-#                            [ DESCRIPTION <description> ]
-#                            [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
-#                            [ PURPOSE <purpose> ]
-#                           )
-#
-#
-#
-# Use this macro to set up information about the named package, which
-# can then be displayed via FEATURE_SUMMARY().  This can be done either
-# directly in the Find-module or in the project which uses the module
-# after the find_package() call.  The features for which information can
-# be set are added automatically by the find_package() command.
-#
-# URL: this should be the homepage of the package, or something similar.
-# Ideally this is set already directly in the Find-module.
-#
-# DESCRIPTION: A short description what that package is, at most one
-# sentence.  Ideally this is set already directly in the Find-module.
-#
-# 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 severly limited.  If a REQUIRED package is not
-# available at buildtime, the project may not even build.  This can be
-# combined with the FATAL_ON_MISSING_REQUIRED_PACKAGES argument for
-# feature_summary().  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 Find-module, but must be set in the project.
-#
-# PURPOSE: This describes which features this package enables in the
-# project, i.e.  it tells the user what functionality he gets 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
-# Find-module, but must be set in the project.
-#
-#
-#
-# Example for setting the info for a package:
-#
-# ::
-#
-#    find_package(LibXml2)
-#    set_package_properties(LibXml2 PROPERTIES
-#                           DESCRIPTION "A XML processing library."
-#                           URL "http://xmlsoft.org/")
-#
-#
-#
-# ::
-#
-#    set_package_properties(LibXml2 PROPERTIES
-#                           TYPE RECOMMENDED
-#                           PURPOSE "Enables HTML-import in MyWordProcessor")
-#    ...
-#    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" )
-#
-#
-#
-# ::
-#
-#     ADD_FEATURE_INFO(<name> <enabled> <description>)
-#
-# Use this macro to add information about a feature with the given
-# <name>.  <enabled> contains whether this feature is enabled or not,
-# <description> is a text describing the feature.  The information can
-# be displayed using feature_summary() for ENABLED_FEATURES and
-# DISABLED_FEATURES respectively.
-#
-# Example for setting the info for a feature:
-#
-# ::
-#
-#    option(WITH_FOO "Help for foo" ON)
-#    add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
-#
-#
-#
-#
-#
-# The following macros are provided for compatibility with previous
-# CMake versions:
-#
-# ::
-#
-#     SET_PACKAGE_INFO(<name> <description> [<url> [<purpose>] ] )
-#
-# Use this macro to set up information about the named package, which
-# can then be displayed via FEATURE_SUMMARY().  This can be done either
-# directly in the Find-module or in the project which uses the module
-# after the find_package() call.  The features for which information can
-# be set are added automatically by the find_package() command.
-#
-# ::
-#
-#     PRINT_ENABLED_FEATURES()
-#
-# Does the same as FEATURE_SUMMARY(WHAT ENABLED_FEATURES DESCRIPTION
-# "Enabled features:")
-#
-# ::
-#
-#     PRINT_DISABLED_FEATURES()
-#
-# Does the same as FEATURE_SUMMARY(WHAT DISABLED_FEATURES DESCRIPTION
-# "Disabled features:")
-#
-# ::
-#
-#     SET_FEATURE_INFO(<name> <description> [<url>] )
-#
-# Does the same as SET_PACKAGE_INFO(<name> <description> <url> )
+#[=======================================================================[.rst:
+FeatureSummary
+--------------
+
+Functions for generating a summary of enabled/disabled features.
+
+These functions can be used to generate a summary of enabled and disabled
+packages and/or feature for a build tree such as::
+
+    -- The following OPTIONAL packages have been found:
+    LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
+       * Enables HTML-import in MyWordProcessor
+       * Enables odt-export in MyWordProcessor
+    PNG , A PNG image library. , <http://www.libpng.org/pub/png/>
+       * Enables saving screenshots
+    -- The following OPTIONAL packages have not been found:
+    Lua51 , The Lua scripting language. , <http://www.lua.org>
+       * Enables macros in MyWordProcessor
+    Foo , Foo provides cool stuff.
+
+Functions
+^^^^^^^^^
+
+#]=======================================================================]
 
 #=============================================================================
 # Copyright 2007-2015 Kitware, Inc.
@@ -280,83 +39,6 @@
 include("${CMAKE_CURRENT_LIST_DIR}/CMakeParseArguments.cmake")
 
 
-function(ADD_FEATURE_INFO _name _enabled _desc)
-  if (${_enabled})
-    set_property(GLOBAL APPEND PROPERTY ENABLED_FEATURES "${_name}")
-  else ()
-    set_property(GLOBAL APPEND PROPERTY DISABLED_FEATURES "${_name}")
-  endif ()
-
-  set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_desc}" )
-endfunction()
-
-
-
-function(SET_PACKAGE_PROPERTIES _name _props)
-  if(NOT "${_props}" STREQUAL "PROPERTIES")
-    message(FATAL_ERROR "PROPERTIES keyword is missing in SET_PACKAGE_PROPERTIES() call.")
-  endif()
-
-  set(options ) # none
-  set(oneValueArgs DESCRIPTION URL TYPE PURPOSE )
-  set(multiValueArgs ) # none
-
-  CMAKE_PARSE_ARGUMENTS(_SPP "${options}" "${oneValueArgs}" "${multiValueArgs}"  ${ARGN})
-
-  if(_SPP_UNPARSED_ARGUMENTS)
-    message(FATAL_ERROR "Unknown keywords given to SET_PACKAGE_PROPERTIES(): \"${_SPP_UNPARSED_ARGUMENTS}\"")
-  endif()
-
-  if(_SPP_DESCRIPTION)
-    get_property(_info  GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION)
-    if(_info AND NOT "${_info}" STREQUAL "${_SPP_DESCRIPTION}")
-      message(STATUS "Warning: Property DESCRIPTION for package ${_name} already set to \"${_info}\", overriding it with \"${_SPP_DESCRIPTION}\"")
-    endif()
-
-    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}")
-      message(STATUS "Warning: Property URL already set to \"${_info}\", overriding it with \"${_SPP_URL}\"")
-    endif()
-
-    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}" )
-  endif()
-
-  # handle the TYPE
-  if(NOT _SPP_TYPE)
-    set(_SPP_TYPE OPTIONAL)
-  endif()
-
-  # List the supported types, according to their priority
-  set(validTypes "RUNTIME" "OPTIONAL" "RECOMMENDED" "REQUIRED" )
-  list(FIND validTypes ${_SPP_TYPE} _typeIndexInList)
-  if("${_typeIndexInList}" STREQUAL "-1" )
-    message(FATAL_ERROR "Bad package property type ${_SPP_TYPE} used in SET_PACKAGE_PROPERTIES(). "
-                        "Valid types are OPTIONAL, RECOMMENDED, REQUIRED and RUNTIME." )
-  endif()
-
-  get_property(_previousType  GLOBAL PROPERTY _CMAKE_${_name}_TYPE)
-  list(FIND validTypes "${_previousType}" _prevTypeIndexInList)
-
-  # make sure a previously set TYPE is not overridden with a lower new TYPE:
-  if("${_typeIndexInList}" GREATER "${_prevTypeIndexInList}")
-    set_property(GLOBAL PROPERTY _CMAKE_${_name}_TYPE "${_SPP_TYPE}" )
-  endif()
-
-endfunction()
-
-
-
 function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet)
 
   set(_type "ANY")
@@ -439,6 +121,97 @@ function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet)
 endfunction()
 
 
+#[=======================================================================[.rst:
+.. command:: feature_summary
+
+  ::
+
+    feature_summary( [FILENAME <file>]
+                     [APPEND]
+                     [VAR <variable_name>]
+                     [INCLUDE_QUIET_PACKAGES]
+                     [FATAL_ON_MISSING_REQUIRED_PACKAGES]
+                     [DESCRIPTION "Found packages:"]
+                     WHAT (ALL | PACKAGES_FOUND | PACKAGES_NOT_FOUND
+                          | ENABLED_FEATURES | DISABLED_FEATURES)
+                   )
+
+  The ``feature_summary()`` macro can be used to print information about
+  enabled or disabled packages or 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 ``set_package_properties()``
+  to add more useful information, like e.g.  a download URL for the
+  respective package or their purpose in the project.
+
+  The ``WHAT`` option is the only mandatory option.  Here you specify 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
+  ``OPTIONAL_PACKAGES_FOUND``
+   only those packages which have been found which have the type OPTIONAL
+  ``OPTIONAL_PACKAGES_NOT_FOUND``
+   only those packages which have not been found which have the type OPTIONAL
+  ``RECOMMENDED_PACKAGES_FOUND``
+   only those packages which have been found which have the type RECOMMENDED
+  ``RECOMMENDED_PACKAGES_NOT_FOUND``
+   only those packages which have not been found which have the type RECOMMENDED
+  ``REQUIRED_PACKAGES_FOUND``
+   only those packages which have been found which have the type REQUIRED
+  ``REQUIRED_PACKAGES_NOT_FOUND``
+   only those packages which have not been found which have the type REQUIRED
+  ``RUNTIME_PACKAGES_FOUND``
+   only those packages which have been found which have the type RUNTIME
+  ``RUNTIME_PACKAGES_NOT_FOUND``
+   only those packages which have not been found which have the type RUNTIME
+
+  With the exception of the ``ALL`` value, these values can be combined
+  in order to customize the output. For example:
+
+  .. code-block:: cmake
+
+    feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
+
+  If a ``FILENAME`` is given, the information is printed into this file.  If
+  ``APPEND`` is used, it is appended to this file, otherwise the file is
+  overwritten if it already existed.  If the VAR option is used, the
+  information is "printed" into the specified variable.  If ``FILENAME`` is
+  not used, the information is printed to the terminal.  Using the
+  ``DESCRIPTION`` option a description or headline can be set which will be
+  printed above the actual content.  If ``INCLUDE_QUIET_PACKAGES`` is given,
+  packages which have been searched with ``find_package(... QUIET)`` will
+  also be listed.  By default they are skipped.  If
+  ``FATAL_ON_MISSING_REQUIRED_PACKAGES`` is given, CMake will abort if a
+  package which is marked as ``REQUIRED`` has not been found.
+
+  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 QUIET packages:
+
+  .. code-block:: cmake
+
+   include(FeatureSummary)
+   feature_summary(WHAT ENABLED_FEATURES
+                   INCLUDE_QUIET_PACKAGES
+                   DESCRIPTION "Enabled Features:"
+                   VAR enabledFeaturesText)
+   message(STATUS "${enabledFeaturesText}")
+#]=======================================================================]
 
 function(FEATURE_SUMMARY)
 # CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
@@ -558,9 +331,198 @@ function(FEATURE_SUMMARY)
 
 endfunction()
 
+#[=======================================================================[.rst:
+.. command:: set_package_properties
+
+  ::
+
+    set_package_properties(<name> PROPERTIES
+                           [ URL <url> ]
+                           [ DESCRIPTION <description> ]
+                           [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
+                           [ PURPOSE <purpose> ]
+                          )
+
+  Use this macro to set up information about the named package, which
+  can then be displayed via FEATURE_SUMMARY().  This can be done either
+  directly in the Find-module or in the project which uses the module
+  after the find_package() call.  The features for which information can
+  be set are added automatically by the find_package() command.
+
+  ``URL <url>``
+    This should be the homepage of the package, or something similar.
+    Ideally this is set already directly in the Find-module.
+
+  ``DESCRIPTION <description>``
+    A short description what that package is, at most one sentence.
+    Ideally this is set already directly in the Find-module.
+
+  ``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 severly limited.  If a ``REQUIRED`` package is not
+    available at buildtime, the project may not even build.  This can be
+    combined with the ``FATAL_ON_MISSING_REQUIRED_PACKAGES`` argument for
+    ``feature_summary()``.  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 Find-module, but must be set in the project.
+
+
+  ``PURPOSE <purpose>``
+    This describes which features this package enables in the
+    project, i.e.  it tells the user what functionality he gets 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
+    Find-module, but must be set in the project.
+
+  Example for setting the info for a package:
+
+  .. code-block:: cmake
+
+    find_package(LibXml2)
+    set_package_properties(LibXml2 PROPERTIES
+                           DESCRIPTION "A XML processing 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.")
+  endif()
+
+  set(options ) # none
+  set(oneValueArgs DESCRIPTION URL TYPE PURPOSE )
+  set(multiValueArgs ) # none
+
+  CMAKE_PARSE_ARGUMENTS(_SPP "${options}" "${oneValueArgs}" "${multiValueArgs}"  ${ARGN})
+
+  if(_SPP_UNPARSED_ARGUMENTS)
+    message(FATAL_ERROR "Unknown keywords given to SET_PACKAGE_PROPERTIES(): \"${_SPP_UNPARSED_ARGUMENTS}\"")
+  endif()
+
+  if(_SPP_DESCRIPTION)
+    get_property(_info  GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION)
+    if(_info AND NOT "${_info}" STREQUAL "${_SPP_DESCRIPTION}")
+      message(STATUS "Warning: Property DESCRIPTION for package ${_name} already set to \"${_info}\", overriding it with \"${_SPP_DESCRIPTION}\"")
+    endif()
+
+    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}")
+      message(STATUS "Warning: Property URL already set to \"${_info}\", overriding it with \"${_SPP_URL}\"")
+    endif()
+
+    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}" )
+  endif()
+
+  # handle the TYPE
+  if(NOT _SPP_TYPE)
+    set(_SPP_TYPE OPTIONAL)
+  endif()
+
+  # List the supported types, according to their priority
+  set(validTypes "RUNTIME" "OPTIONAL" "RECOMMENDED" "REQUIRED" )
+  list(FIND validTypes ${_SPP_TYPE} _typeIndexInList)
+  if("${_typeIndexInList}" STREQUAL "-1" )
+    message(FATAL_ERROR "Bad package property type ${_SPP_TYPE} used in SET_PACKAGE_PROPERTIES(). "
+                        "Valid types are OPTIONAL, RECOMMENDED, REQUIRED and RUNTIME." )
+  endif()
+
+  get_property(_previousType  GLOBAL PROPERTY _CMAKE_${_name}_TYPE)
+  list(FIND validTypes "${_previousType}" _prevTypeIndexInList)
+
+  # make sure a previously set TYPE is not overridden with a lower new TYPE:
+  if("${_typeIndexInList}" GREATER "${_prevTypeIndexInList}")
+    set_property(GLOBAL PROPERTY _CMAKE_${_name}_TYPE "${_SPP_TYPE}" )
+  endif()
+
+endfunction()
+
+#[=======================================================================[.rst:
+.. command:: add_feature_info
+
+  ::
+
+    add_feature_info(<name> <enabled> <description>)
+
+  Use this macro to add information about a feature with the given ``<name>``.
+  ``<enabled>`` contains whether this feature is enabled or not.
+  ``<description>`` is a text describing the feature.  The information can
+  be displayed using ``feature_summary()`` for ``ENABLED_FEATURES`` and
+  ``DISABLED_FEATURES`` respectively.
+
+  Example for setting the info for a feature:
+
+  .. code-block:: cmake
+
+     option(WITH_FOO "Help for foo" ON)
+     add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
+#]=======================================================================]
+function(ADD_FEATURE_INFO _name _enabled _desc)
+  if (${_enabled})
+    set_property(GLOBAL APPEND PROPERTY ENABLED_FEATURES "${_name}")
+  else ()
+    set_property(GLOBAL APPEND PROPERTY DISABLED_FEATURES "${_name}")
+  endif ()
+
+  set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_desc}" )
+endfunction()
+
 
 # The stuff below is only kept for compatibility
 
+#[=======================================================================[.rst:
+Legacy Macros
+^^^^^^^^^^^^^
+
+The following macros are provided for compatibility with previous
+CMake versions:
+
+.. command:: set_package_info
+
+  ::
+
+    set_package_info(<name> <description> [ <url> [<purpose>] ])
+
+  Use this macro to set up information about the named package, which
+  can then be displayed via ``feature_summary()``.  This can be done either
+  directly in the Find-module or in the project which uses the module
+  after the :command:`find_package` call.  The features for which information
+  can be set are added automatically by the ``find_package()`` command.
+#]=======================================================================]
 function(SET_PACKAGE_INFO _name _desc)
   unset(_url)
   unset(_purpose)
@@ -579,20 +541,51 @@ function(SET_PACKAGE_INFO _name _desc)
   endif()
 endfunction()
 
+#[=======================================================================[.rst:
+.. command:: set_feature_info
 
+  ::
 
+    set_feature_info(<name> <description> [<url>])
+
+  Does the same as::
+
+    set_package_info(<name> <description> <url>)
+#]=======================================================================]
 function(SET_FEATURE_INFO)
   SET_PACKAGE_INFO(${ARGN})
 endfunction()
 
+#[=======================================================================[.rst:
+.. command:: print_enabled_features
+
+  ::
+
+    print_enabled_features()
 
+  Does the same as
 
+  .. code-block:: cmake
+
+    feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
+#]=======================================================================]
 function(PRINT_ENABLED_FEATURES)
   FEATURE_SUMMARY(WHAT ENABLED_FEATURES  DESCRIPTION "Enabled features:")
 endfunction()
 
+#[=======================================================================[.rst:
+.. command:: print_disabled_features
+
+  ::
+
+    print_disabled_features()
+
+  Does the same as
 
+  .. code-block:: cmake
 
+    feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
+#]=======================================================================]
 function(PRINT_DISABLED_FEATURES)
   FEATURE_SUMMARY(WHAT DISABLED_FEATURES  DESCRIPTION "Disabled features:")
 endfunction()