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, 356 insertions, 356 deletions

diff --git a/modules/ECMGenerateExportHeader.cmake b/modules/ECMGenerateExportHeader.cmake
index 0ee3b411..170531e7 100644
--- a/modules/ECMGenerateExportHeader.cmake
+++ b/modules/ECMGenerateExportHeader.cmake
@@ -1,363 +1,363 @@
-#.rst:
-# ECMGenerateExportHeader
-# -----------------------
-#
-# This module provides the ``ecm_generate_export_header`` function for
-# generating export macros for libraries with version-based control over
-# visibility of and compiler warnings for deprecated API for the library user,
-# as well as over excluding deprecated API and their implementation when
-# building the library itself.
-#
-# For preparing some values useful in the context it also provides a function
-# ``ecm_export_header_format_version``.
-#
-# ::
-#
-#   ecm_generate_export_header(<library_target_name>
-#       VERSION <version>
-#       [BASE_NAME <base_name>]
-#       [GROUP_BASE_NAME <group_base_name>]
-#       [EXPORT_MACRO_NAME <export_macro_name>]
-#       [EXPORT_FILE_NAME <export_file_name>]
-#       [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
-#       [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
-#       [INCLUDE_GUARD_NAME <include_guard_name>]
-#       [STATIC_DEFINE <static_define>]
-#       [PREFIX_NAME <prefix_name>]
-#       [DEPRECATED_BASE_VERSION <deprecated_base_version>]
-#       [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
-#       [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
-#       [NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE]
-#       [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
-#       [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
-#   )
-#
-# ``VERSION`` specifies the version of the library, given in the format
-# "<major>.<minor>.<patchlevel>".
-#
-# ``GROUP_BASE_NAME`` specifies the name to use for the macros defining
-# library group default values. If set, this will generate code supporting
-# ``<group_base_name>_NO_DEPRECATED_WARNINGS``,
-# ``<group_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``,
-# ``<group_base_name>_DEPRECATED_WARNINGS_SINCE``  and
-# ``<group_base_name>_NO_DEPRECATED`` (see below).
-# If not set, the generated code will ignore any such macros.
-#
-# ``DEPRECATED_BASE_VERSION`` specifies the default version before and at which
-# deprecated API is disabled. Possible values are "0", "CURRENT" (which
-# resolves to <version>) and a version string in the format
-# "<major>.<minor>.<patchlevel>". The default is the value of
-# "<exclude_deprecated_before_and_at_version>" if set, or "<major>.0.0", with
-# <major> taken from <version>.
-#
-# ``DEPRECATION_VERSIONS`` specifies versions in "<major>.<minor>" format in
-# which API was declared deprecated. Any version used with the generated
-# macro ``<prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text)``
-# or ``<prefix_name><base_name>_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)``
-# needs to be listed here, otherwise the macro will fail to work.
-#
-# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` specifies the version for which all API
-# deprecated before and at should be excluded from the build completely.
-# Possible values are "0" (default), "CURRENT" (which resolves to <version>)
-# and a version string in the format "<major>.<minor>.<patchlevel>".
-#
-# ``NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE`` specifies that the definition
-# ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` will
-# not be set for the library inside its own build, and thus will be defined
-# by either explicit definition in the build system configuration or by the
-# default value mechanism (see below).
-# The default is that it is set for the build, to the version specified by
-# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so no deprecation warnings are
-# done for any own deprecated API used in the library implementation itself.
-#
-# ``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` specifies that the definition
-# ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` will
-# not be set in the public interface of the library inside its own build, and
-# the same for the definition
-# ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` (if not
-# disabled by ``NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE`` already).
-# The default is that they are set, to the version specified by
-# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so e.g. test and examples part of the
-# project automatically build against the full API included in the build and
-# without any deprecation warnings for it.
-#
-#
-# The function ``ecm_generate_export_header`` defines C++ preprocessor macros
-# in the generated export header, some for use in the sources of the library
-# the header is generated for, other for use by projects linking agsinst the
-# library.
-#
-# The macros for use in the library C++ sources are these, next to those also
-# defined by `GenerateExportHeader
-# <https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html>`_:
-#
-# ``<prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor, text)``
-#   to use to conditionally set a
-#   ``<prefix_name><uppercase_base_name>_DEPRECATED`` macro for a class, struct
-#   or function (other elements to be supported in future versions), depending
-#   on the visibility macro flags set (see below)
-#
-# ``<prefix_name><uppercase_base_name>_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)``
-#   to use to conditionally set a
-#   ``<prefix_name><uppercase_base_name>_DEPRECATED`` macro for a class, struct
-#   or function (other elements to be supported in future versions), depending
-#   on the visibility macro flags set (see below), with ``major`` & ``minor``
-#   applied for the logic and ``textmajor`` & ``textminor`` for the warnings message.
-#   Useful for retroactive tagging of API for the compiler without injecting the
-#   API into the compiler warning conditions of already released versions.
-#   Since 5.71.
-#
-# ``<prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, minor)``
-#   evaluates to ``TRUE`` or ``FALSE`` depending on the visibility macro flags
-#   set (see below). To be used mainly with ``#if``/``#endif`` to mark sections
-#   of code which should be included depending on the visibility requested.
-#
-# ``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)``
-#   evaluates to ``TRUE`` or ``FALSE`` depending on the value of
-#   ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``. To be used mainly with
-#   ``#if``/``#endif`` to mark sections of two types of code: implementation
-#   code for deprecated API and declaration code of deprecated API which only
-#   may be disabled at build time of the library for BC reasons (e.g. virtual
-#   methods, see notes below).
-#
-# ``<prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT``
-#   holds the version used to exclude deprecated API at build time of the
-#   library.
-#
-# The macros used to control visibility when building against the library are:
-#
-# ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``
-#   definition to set to a value in single hex number version notation
-#   (``0x<major><minor><patchlevel>``).
-#
-# ``<prefix_name><uppercase_base_name>_NO_DEPRECATED``
-#   flag to define to disable all deprecated API, being a shortcut for
-#   settings ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``
-#   to the current version. If both are set, this flag overrules.
-#
-# ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE``
-#   definition to set to a value in single hex number version notation
-#   (``0x<major><minor><patchlevel>``). Warnings will be only activated for
-#   API deprecated up to and including the version. If
-#   ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``
-#   is set (directly or via the group default), it will default to that
-#   version, resulting in no warnings. Otherwise the default is the current
-#   version, resulting in warnings for all deprecated API.
-#
-# ``<prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS``
-#   flag to define to disable all deprecation warnings, being a shortcut for
-#   setting ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE``
-#   to "0". If both are set, this flag overrules.
-#
-# When the ``GROUP_BASE_NAME`` has been used, the same macros but with the
-# given ``<group_base_name>`` prefix are available to define the defaults of
-# these macros, if not explicitly set.
-#
-# Note: The tricks applied here for hiding deprecated API to the compiler
-# when building against a library do not work for all deprecated API:
-#
-# * virtual methods need to stay visible to the compiler to build proper
-#   virtual method tables for subclasses
-# * enumerators from enums cannot be simply removed, as this changes
-#   auto values of following enumerators, also can poke holes in enumerator
-#   series used as index into tables
-#
-# In such cases the API can be only "hidden" at build time of the library,
-# itself, by generated hard coded macro settings, using
-# ``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)``.
-#
-# Examples:
-#
-# Preparing a library "Foo" created by target "foo", which is part of a group
-# of libraries "Bar", where some API of "Foo" got deprecated at versions
-# 5.0 & 5.12:
-#
-# .. code-block:: cmake
-#
-#   ecm_generate_export_header(foo
-#       GROUP_BASE_NAME BAR
-#       VERSION ${FOO_VERSION}
-#       DEPRECATION_VERSIONS 5.0 5.12
-#   )
-#
-# In the library "Foo" sources in the headers the API would be prepared like
-# this, using the generated macros ``FOO_ENABLE_DEPRECATED_SINCE`` and
-# ``FOO_DEPRECATED_VERSION``:
-#
-# .. code-block:: cpp
-#
-#   #include <foo_export.h>
-#
-#   #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
-#   /**
-#     * @deprecated Since 5.0
-#     */
-#   FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
-#   FOO_EXPORT void doFoo();
-#   #endif
-#
-#   #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
-#   /**
-#     * @deprecated Since 5.12
-#     */
-#   FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
-#   FOO_EXPORT void doBar();
-#   #endif
-#
-# Projects linking against the "Foo" library can control which part of its
-# deprecated API should be hidden to the compiler by adding a definition
-# using the ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` macro variable set to the
-# desired value (in version hex number notation):
-#
-# .. code-block:: cmake
-#
-#   add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
-#
-# Or using the macro variable of the group:
-#
-# .. code-block:: cmake
-#
-#   add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
-#
-# If both are specified, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` will take
-# precedence.
-#
-# To build a variant of a library with some deprecated API completely left
-# out from the build, not only optionally invisible to consumers, one uses the
-# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` parameter. This is best combined with a
-# cached CMake variable.
-#
-# .. code-block:: cmake
-#
-#   set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
-#
-#   ecm_generate_export_header(foo
-#       VERSION ${FOO_VERSION}
-#       EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
-#       DEPRECATION_VERSIONS 5.0 5.12
-#   )
-#
-# The macros used in the headers for library consumers are reused for
-# disabling the API excluded in the build of the library. For disabling the
-# implementation of that API as well as for disabling deprecated API which
-# only can be disabled at build time of the library for BC reasons, one
-# uses the generated macro ``FOO_BUILD_DEPRECATED_SINCE``, like this:
-#
-# .. code-block:: cpp
-#
-#   #include <foo_export.h>
-#
-#   enum Bars {
-#       One,
-#   #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
-#       Two,
-#   #endif
-#       Three,
-#   };
-#
-#   #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
-#   /**
-#     * @deprecated Since 5.0
-#     */
-#   FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
-#   FOO_EXPORT void doFoo();
-#   #endif
-#
-#   #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
-#   /**
-#     * @deprecated Since 5.12
-#     */
-#   FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
-#   FOO_EXPORT void doBar();
-#   #endif
-#
-#   class FOO_EXPORT Foo {
-#   public:
-#   #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
-#       /**
-#         * @deprecated Since 5.0
-#         */
-#       FOO_DEPRECATED_VERSION(5, 0, "Feature removed")
-#       virtual void doWhat();
-#   #endif
-#   };
-#
-# .. code-block:: cpp
-#
-#   #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
-#   void doFoo()
-#   {
-#       // [...]
-#   }
-#   #endif
-#
-#   #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
-#   void doBar()
-#   {
-#       // [...]
-#   }
-#   #endif
-#
-#   #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
-#   void Foo::doWhat()
-#   {
-#       // [...]
-#   }
-#   #endif
-#
-# So e.g. if ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` is set to "5.0.0", the
-# enumerator ``Two`` as well as the methods ``::doFoo()`` and ``Foo::doWhat()``
-# will be not available to library consumers. The methods will not have been
-# compiled into the library binary, and the declarations will be hidden to the
-# compiler, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` also cannot be used to
-# reactivate them.
-#
-# When using the ``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` and the project
-# for the "Foo" library includes also tests and examples linking against the
-# library and using deprecated API (like tests covering it), one better
-# explicitly sets ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` for those targets
-# to the version before and at which all deprecated API has been excluded from
-# the build.
-# Even more when building against other libraries from the same group "Bar" and
-# disabling some deprecated API of those libraries using the group macro
-# ``BAR_DISABLE_DEPRECATED_BEFORE_AND_AT``, which also works as default for
-# ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT``.
-#
-# To get the hex number style value the helper macro
-# ``ecm_export_header_format_version()`` will be used:
-#
-# .. code-block:: cmake
-#
-#   set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
-#
-#   ecm_generate_export_header(foo
-#       VERSION ${FOO_VERSION}
-#       GROUP_BASE_NAME BAR
-#       EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
-#       NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
-#       DEPRECATION_VERSIONS 5.0 5.12
-#   )
-#
-#   ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
-#       CURRENT_VERSION ${FOO_VERSION}
-#       HEXNUMBER_VAR foo_no_deprecated_before_and_at
-#   )
-#
-#   # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
-#   add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
-#
-#   add_executable(app app.cpp)
-#   target_link_libraries(app foo)
-#   target_compile_definitions(app
-#        PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
-#
-# Since 5.64.0.
-
-#=============================================================================
 # SPDX-FileCopyrightText: 2019 Friedrich W. H. Kossebau <kossebau@kde.org>
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
+#[=======================================================================[.rst:
+ECMGenerateExportHeader
+-----------------------
+
+This module provides the ``ecm_generate_export_header`` function for
+generating export macros for libraries with version-based control over
+visibility of and compiler warnings for deprecated API for the library user,
+as well as over excluding deprecated API and their implementation when
+building the library itself.
+
+For preparing some values useful in the context it also provides a function
+``ecm_export_header_format_version``.
+
+::
+
+  ecm_generate_export_header(<library_target_name>
+      VERSION <version>
+      [BASE_NAME <base_name>]
+      [GROUP_BASE_NAME <group_base_name>]
+      [EXPORT_MACRO_NAME <export_macro_name>]
+      [EXPORT_FILE_NAME <export_file_name>]
+      [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
+      [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
+      [INCLUDE_GUARD_NAME <include_guard_name>]
+      [STATIC_DEFINE <static_define>]
+      [PREFIX_NAME <prefix_name>]
+      [DEPRECATED_BASE_VERSION <deprecated_base_version>]
+      [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
+      [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
+      [NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE]
+      [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
+      [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
+  )
+
+``VERSION`` specifies the version of the library, given in the format
+"<major>.<minor>.<patchlevel>".
+
+``GROUP_BASE_NAME`` specifies the name to use for the macros defining
+library group default values. If set, this will generate code supporting
+``<group_base_name>_NO_DEPRECATED_WARNINGS``,
+``<group_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``,
+``<group_base_name>_DEPRECATED_WARNINGS_SINCE``  and
+``<group_base_name>_NO_DEPRECATED`` (see below).
+If not set, the generated code will ignore any such macros.
+
+``DEPRECATED_BASE_VERSION`` specifies the default version before and at which
+deprecated API is disabled. Possible values are "0", "CURRENT" (which
+resolves to <version>) and a version string in the format
+"<major>.<minor>.<patchlevel>". The default is the value of
+"<exclude_deprecated_before_and_at_version>" if set, or "<major>.0.0", with
+<major> taken from <version>.
+
+``DEPRECATION_VERSIONS`` specifies versions in "<major>.<minor>" format in
+which API was declared deprecated. Any version used with the generated
+macro ``<prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text)``
+or ``<prefix_name><base_name>_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)``
+needs to be listed here, otherwise the macro will fail to work.
+
+``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` specifies the version for which all API
+deprecated before and at should be excluded from the build completely.
+Possible values are "0" (default), "CURRENT" (which resolves to <version>)
+and a version string in the format "<major>.<minor>.<patchlevel>".
+
+``NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE`` specifies that the definition
+``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` will
+not be set for the library inside its own build, and thus will be defined
+by either explicit definition in the build system configuration or by the
+default value mechanism (see below).
+The default is that it is set for the build, to the version specified by
+``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so no deprecation warnings are
+done for any own deprecated API used in the library implementation itself.
+
+``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` specifies that the definition
+``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` will
+not be set in the public interface of the library inside its own build, and
+the same for the definition
+``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` (if not
+disabled by ``NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE`` already).
+The default is that they are set, to the version specified by
+``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so e.g. test and examples part of the
+project automatically build against the full API included in the build and
+without any deprecation warnings for it.
+
+
+The function ``ecm_generate_export_header`` defines C++ preprocessor macros
+in the generated export header, some for use in the sources of the library
+the header is generated for, other for use by projects linking agsinst the
+library.
+
+The macros for use in the library C++ sources are these, next to those also
+defined by `GenerateExportHeader
+<https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html>`_:
+
+``<prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor, text)``
+  to use to conditionally set a
+  ``<prefix_name><uppercase_base_name>_DEPRECATED`` macro for a class, struct
+  or function (other elements to be supported in future versions), depending
+  on the visibility macro flags set (see below)
+
+``<prefix_name><uppercase_base_name>_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)``
+  to use to conditionally set a
+  ``<prefix_name><uppercase_base_name>_DEPRECATED`` macro for a class, struct
+  or function (other elements to be supported in future versions), depending
+  on the visibility macro flags set (see below), with ``major`` & ``minor``
+  applied for the logic and ``textmajor`` & ``textminor`` for the warnings message.
+  Useful for retroactive tagging of API for the compiler without injecting the
+  API into the compiler warning conditions of already released versions.
+  Since 5.71.
+
+``<prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, minor)``
+  evaluates to ``TRUE`` or ``FALSE`` depending on the visibility macro flags
+  set (see below). To be used mainly with ``#if``/``#endif`` to mark sections
+  of code which should be included depending on the visibility requested.
+
+``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)``
+  evaluates to ``TRUE`` or ``FALSE`` depending on the value of
+  ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``. To be used mainly with
+  ``#if``/``#endif`` to mark sections of two types of code: implementation
+  code for deprecated API and declaration code of deprecated API which only
+  may be disabled at build time of the library for BC reasons (e.g. virtual
+  methods, see notes below).
+
+``<prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT``
+  holds the version used to exclude deprecated API at build time of the
+  library.
+
+The macros used to control visibility when building against the library are:
+
+``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``
+  definition to set to a value in single hex number version notation
+  (``0x<major><minor><patchlevel>``).
+
+``<prefix_name><uppercase_base_name>_NO_DEPRECATED``
+  flag to define to disable all deprecated API, being a shortcut for
+  settings ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``
+  to the current version. If both are set, this flag overrules.
+
+``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE``
+  definition to set to a value in single hex number version notation
+  (``0x<major><minor><patchlevel>``). Warnings will be only activated for
+  API deprecated up to and including the version. If
+  ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``
+  is set (directly or via the group default), it will default to that
+  version, resulting in no warnings. Otherwise the default is the current
+  version, resulting in warnings for all deprecated API.
+
+``<prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS``
+  flag to define to disable all deprecation warnings, being a shortcut for
+  setting ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE``
+  to "0". If both are set, this flag overrules.
+
+When the ``GROUP_BASE_NAME`` has been used, the same macros but with the
+given ``<group_base_name>`` prefix are available to define the defaults of
+these macros, if not explicitly set.
+
+Note: The tricks applied here for hiding deprecated API to the compiler
+when building against a library do not work for all deprecated API:
+
+* virtual methods need to stay visible to the compiler to build proper
+  virtual method tables for subclasses
+* enumerators from enums cannot be simply removed, as this changes
+  auto values of following enumerators, also can poke holes in enumerator
+  series used as index into tables
+
+In such cases the API can be only "hidden" at build time of the library,
+itself, by generated hard coded macro settings, using
+``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)``.
+
+Examples:
+
+Preparing a library "Foo" created by target "foo", which is part of a group
+of libraries "Bar", where some API of "Foo" got deprecated at versions
+5.0 & 5.12:
+
+.. code-block:: cmake
+
+  ecm_generate_export_header(foo
+      GROUP_BASE_NAME BAR
+      VERSION ${FOO_VERSION}
+      DEPRECATION_VERSIONS 5.0 5.12
+  )
+
+In the library "Foo" sources in the headers the API would be prepared like
+this, using the generated macros ``FOO_ENABLE_DEPRECATED_SINCE`` and
+``FOO_DEPRECATED_VERSION``:
+
+.. code-block:: cpp
+
+  #include <foo_export.h>
+
+  #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
+  /**
+    * @deprecated Since 5.0
+    */
+  FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
+  FOO_EXPORT void doFoo();
+  #endif
+
+  #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
+  /**
+    * @deprecated Since 5.12
+    */
+  FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
+  FOO_EXPORT void doBar();
+  #endif
+
+Projects linking against the "Foo" library can control which part of its
+deprecated API should be hidden to the compiler by adding a definition
+using the ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` macro variable set to the
+desired value (in version hex number notation):
+
+.. code-block:: cmake
+
+  add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
+
+Or using the macro variable of the group:
+
+.. code-block:: cmake
+
+  add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
+
+If both are specified, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` will take
+precedence.
+
+To build a variant of a library with some deprecated API completely left
+out from the build, not only optionally invisible to consumers, one uses the
+``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` parameter. This is best combined with a
+cached CMake variable.
+
+.. code-block:: cmake
+
+  set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
+
+  ecm_generate_export_header(foo
+      VERSION ${FOO_VERSION}
+      EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
+      DEPRECATION_VERSIONS 5.0 5.12
+  )
+
+The macros used in the headers for library consumers are reused for
+disabling the API excluded in the build of the library. For disabling the
+implementation of that API as well as for disabling deprecated API which
+only can be disabled at build time of the library for BC reasons, one
+uses the generated macro ``FOO_BUILD_DEPRECATED_SINCE``, like this:
+
+.. code-block:: cpp
+
+  #include <foo_export.h>
+
+  enum Bars {
+      One,
+  #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
+      Two,
+  #endif
+      Three,
+  };
+
+  #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
+  /**
+    * @deprecated Since 5.0
+    */
+  FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
+  FOO_EXPORT void doFoo();
+  #endif
+
+  #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
+  /**
+    * @deprecated Since 5.12
+    */
+  FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
+  FOO_EXPORT void doBar();
+  #endif
+
+  class FOO_EXPORT Foo {
+  public:
+  #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
+      /**
+        * @deprecated Since 5.0
+        */
+      FOO_DEPRECATED_VERSION(5, 0, "Feature removed")
+      virtual void doWhat();
+  #endif
+  };
+
+.. code-block:: cpp
+
+  #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
+  void doFoo()
+  {
+      // [...]
+  }
+  #endif
+
+  #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
+  void doBar()
+  {
+      // [...]
+  }
+  #endif
+
+  #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
+  void Foo::doWhat()
+  {
+      // [...]
+  }
+  #endif
+
+So e.g. if ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` is set to "5.0.0", the
+enumerator ``Two`` as well as the methods ``::doFoo()`` and ``Foo::doWhat()``
+will be not available to library consumers. The methods will not have been
+compiled into the library binary, and the declarations will be hidden to the
+compiler, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` also cannot be used to
+reactivate them.
+
+When using the ``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` and the project
+for the "Foo" library includes also tests and examples linking against the
+library and using deprecated API (like tests covering it), one better
+explicitly sets ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` for those targets
+to the version before and at which all deprecated API has been excluded from
+the build.
+Even more when building against other libraries from the same group "Bar" and
+disabling some deprecated API of those libraries using the group macro
+``BAR_DISABLE_DEPRECATED_BEFORE_AND_AT``, which also works as default for
+``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT``.
+
+To get the hex number style value the helper macro
+``ecm_export_header_format_version()`` will be used:
+
+.. code-block:: cmake
+
+  set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
+
+  ecm_generate_export_header(foo
+      VERSION ${FOO_VERSION}
+      GROUP_BASE_NAME BAR
+      EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
+      NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
+      DEPRECATION_VERSIONS 5.0 5.12
+  )
+
+  ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
+      CURRENT_VERSION ${FOO_VERSION}
+      HEXNUMBER_VAR foo_no_deprecated_before_and_at
+  )
+
+  # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
+  add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
+
+  add_executable(app app.cpp)
+  target_link_libraries(app foo)
+  target_compile_definitions(app
+       PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
+
+Since 5.64.0.
+#]=======================================================================]
+
 include(GenerateExportHeader)
 include(CMakeParseArguments)