Add documentation generation using Sphinx

This is deliberately modelled very closely on CMake's documentation
system.  It's a hefty patch, because it involved changing all the
documentation to be in reStructuredText format.  I also cleaned up the
copyright/license statements at the same time.

Note that the find modules contain the full license, due to the fact
that ecm_use_find_module() copies them out of the ECM distribution.

13 files changed, 543 insertions, 261 deletions

diff --git a/modules/ECMAddTests.cmake b/modules/ECMAddTests.cmake
index 67026eca..9052d886 100644
--- a/modules/ECMAddTests.cmake
+++ b/modules/ECMAddTests.cmake
@@ -1,28 +1,50 @@
-include(ECMMarkAsTest)
-include(ECMMarkNonGuiExecutable)
-# This file provides the functions ecm_add_test() and ecm_add_tests().
+#.rst:
+# ECMAddTests
+# -----------
+#
+# Add test executables.
+#
+# ::
+#
+#   ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]]
+#                          [TEST_NAME <name>]
+#                          [NAME_PREFIX <prefix>]
+#                          [GUI])
 #
-# ecm_add_test(<sources> TEST_NAME <name> NAME_PREFIX <prefix> LINK_LIBRARIES <libraries/targets> [GUI])
+# Add a new unit test using the passed source files. The parameter TEST_NAME is
+# used to set the name of the resulting test. It may be omitted if there is
+# exactly one source file. In that case the name of the source file (without the
+# file extension) will be used as the test name.  If the flag GUI is passed the
+# test binary will be a GUI executable, otherwise the resulting binary will be a
+# console application.  The test will be linked against the libraries and/or
+# targets passed to LINK_LIBRARIES.
 #
-# Add a new unit test using the passed source files. The parameter TEST_NAME is used to set the name
-# of the resulting test. It may be omitted if there is exactly one source file. In that case the name of
-# the source file (without the file extension) will be used as the test name.
-# If the flag GUI is passed the test binary will be a GUI executable, otherwise the resulting
-# binary will be a console application.
 #
-# ecm_add_tests(<sources> NAME_PREFIX <prefix> LINK_LIBRARIES <libraries/targets> [GUI])
+# ::
 #
-# Add a new unit test for every source file passed. The name of the tests will be the name of the
-# corresponding source file minus the file extension. If NAME_PREFIX is set, that string will be
-# prepended to each of the unit test names. Each of the unit tests will be linked against the
-# libraries and/or targets passed in the LINK_LIBRARIES parameter.
-# If the flag GUI is passed the test binary will be a GUI executable, otherwise the resulting
-# binary will be a console application.
+#   ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]]
+#                           [NAME_PREFIX <prefix>]
+#                           [GUI])
 #
-# Copyright (c) 2013, Alexander Richardson, <arichardson.kde@gmail.com>
+# This is a convenient version of ecm_add_test() for when you have many tests
+# that consist of a single source file each.  It behaves like calling
+# ecm_add_test() once for each source file, with the same named arguments.
+
+#=============================================================================
+# Copyright 2013 Alexander Richardson <arichardson.kde@gmail.com>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
+
+include(ECMMarkAsTest)
+include(ECMMarkNonGuiExecutable)
 
 function(ecm_add_test)
   set(options GUI)
diff --git a/modules/ECMCreateQmFromPoFiles.cmake b/modules/ECMCreateQmFromPoFiles.cmake
index f24090b7..92d0d1a8 100644
--- a/modules/ECMCreateQmFromPoFiles.cmake
+++ b/modules/ECMCreateQmFromPoFiles.cmake
@@ -1,12 +1,20 @@
-#  ecm_create_qm_from_po_files(PO_DIR <po_dir>
-#                              POT_NAME <pot_name>
-#                              [DATA_INSTALL_DIR <data_install_dir>]
-#                              [DATA_INSTALL_SUB_DIR <data_install_sub_dir>]
-#                              [CREATE_LOADER <source_file_var>])
+#.rst:
+# ECMCreateQmFromPoFiles
+# ----------------------
 #
-# ecm_create_qm_from_po_files() creates the necessary rules to compile .po
-# files into .qm files, usable by QTranslator. It can also generate a C++ file
-# which takes care of automatically loading those translations.
+# Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
+#
+# ::
+#
+#   ecm_create_qm_from_po_files(PO_DIR <po_dir>
+#                               POT_NAME <pot_name>
+#                               [DATA_INSTALL_DIR <data_install_dir>]
+#                               [DATA_INSTALL_SUB_DIR <data_install_sub_dir>]
+#                               [CREATE_LOADER <source_file_var>])
+#
+# Creates the necessary rules to compile .po files into .qm files, usable by
+# QTranslator. It can also generate a C++ file which takes care of automatically
+# loading those translations.
 #
 # PO_DIR is the path to a directory containing .po files.
 #
@@ -18,7 +26,9 @@
 # DATA_INSTALL_DIR defaults to ${DATA_INSTALL_DIR} if defined, otherwise it uses
 # "share". It must point to a directory which is in the list returned by:
 #
-#     QStandardPath::standardLocations(QStandardPath::GenericDataLocation)
+# .. code-block:: cpp
+#
+#   QStandardPath::standardLocations(QStandardPath::GenericDataLocation)
 #
 # otherwise the C++ loader will fail to load the translations.
 #
@@ -33,14 +43,24 @@
 # at startup. The path of the .cpp file is stored in <source_file_var>. This
 # variable must be added to the list of sources to build, like this:
 #
+# .. code-block:: cmake
+#
 #   ecm_create_qm_from_po_files(PO_DIR po POT_NAME mylib CREATE_LOADER myloader)
 #   set(mylib_SRCS foo.cpp bar.cpp ${myloader})
 #   add_library(mylib ${mylib_SRCS})
+
+#=============================================================================
+# Copyright 2014 Aurélien Gâteau <agateau@kde.org>
 #
-# Copyright (c) 2014, Aurélien Gâteau, <agateau@kde.org>
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
 # This gives us Qt5::lrelease and Qt5::lupdate but unfortunately no Qt5::lconvert
 # See https://bugreports.qt-project.org/browse/QTBUG-37937
diff --git a/modules/ECMDBusAddActivationService.cmake b/modules/ECMDBusAddActivationService.cmake
index d65be03c..128482e3 100644
--- a/modules/ECMDBusAddActivationService.cmake
+++ b/modules/ECMDBusAddActivationService.cmake
@@ -1,35 +1,48 @@
-# Install a DBus ".service" file, so that a program can be started via DBus activation.
+#.rst:
+# ECMDBusAddActivationService
+# ---------------------------
 #
-# ecm_dbus_add_activation_service(inputfile)
+# Install D-Bus activation .service files.
 #
-# This macro will read the input file, generate a .service file from it, and install it
-# into the right directory for the dbus server to find it.
+# ::
 #
-# Note that in the case of custom install prefixes, the user will have to add the prefix
-# to XDG_DATA_DIRS before starting the DBus server.
+#   ecm_dbus_add_activation_service(<inputfile> [<inputfile> [...]])
+#
+# This macro will configure the input file to generate a .service file, and
+# install it into the right directory for the dbus server to find it.
+#
+# Note that in the case of custom install prefixes, the user will have to add
+# the prefix to XDG_DATA_DIRS before starting the DBus server.
 #
 # Example:
+#
+# .. code-block:: cmake
+#
 #   ecm_dbus_add_activation_service(org.mydomain.myapp.service.in)
 #
-# The file org.mydomain.myapp.service.in contains:
+# The file org.mydomain.myapp.service.in contains::
 #
-# [D-BUS Service]
-# Name=org.mydomain.myapp
-# Exec=@CMAKE_INSTALL_PREFIX@/bin/myapp
+#   [D-BUS Service]
+#   Name=org.mydomain.myapp
+#   Exec=@CMAKE_INSTALL_PREFIX@/bin/myapp
 #
 # This will create and install PREFIX/share/dbus-1/services/org.mydomain.myapp.service
 #
 # See http://techbase.kde.org/Development/Tutorials/D-Bus/Autostart_Services for
 # a more complete documentation.
-#
+
+#=============================================================================
 # Copyright 2012 David Faure <faure@kde.org>
 #
 # Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
 # This software is distributed WITHOUT ANY WARRANTY; without even the
 # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 # See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
 macro(ecm_dbus_add_activation_service _sources)
     foreach(_i ${_sources})
@@ -37,6 +50,8 @@ macro(ecm_dbus_add_activation_service _sources)
         string(REGEX REPLACE "\\.service.*$" ".service" _output_file ${_i})
         set(_target ${CMAKE_CURRENT_BINARY_DIR}/${_output_file})
         configure_file(${_service_file} ${_target})
+        # FIXME: document use of ${DBUS_SERVICES_INSTALL_DIR}, and provide a
+        #        fallback
         install(FILES ${_target} DESTINATION ${DBUS_SERVICES_INSTALL_DIR})
     endforeach()
 endmacro()
diff --git a/modules/ECMFindModuleHelpers.cmake b/modules/ECMFindModuleHelpers.cmake
index e38fcaf2..15df9ef0 100644
--- a/modules/ECMFindModuleHelpers.cmake
+++ b/modules/ECMFindModuleHelpers.cmake
@@ -1,13 +1,23 @@
-# Helper macros for find modules
+#.rst:
+# ECMFindModuleHelpers
+# --------------------
+#
+# Helper macros for find modules: ecm_find_package_version_check(),
+# ecm_find_package_parse_components() and
+# ecm_find_package_handle_library_components().
+#
+# ::
 #
 #   ecm_find_package_version_check(<name>)
 #
 # Prints warnings if the CMake version or the project's required CMake version
 # is older than that required by extra-cmake-modules.
 #
+# ::
+#
 #   ecm_find_package_parse_components(<name>
 #       RESULT_VAR <variable>
-#       KNOWN_COMPONENTS <component> [<component>]*
+#       KNOWN_COMPONENTS <component1> [<component2> [...]]
 #       [SKIP_DEPENDENCY_HANDLING])
 #
 # This macro will populate <variable> with a list of components found in
@@ -24,8 +34,10 @@
 # If <component> is listed in <name>_FIND_COMPONENTS, then all its (transitive)
 # dependencies will also be added to <variable>.
 #
+# ::
+#
 #   ecm_find_package_handle_library_components(<name>
-#       COMPONENTS <component> [<component>]*
+#       COMPONENTS <component> [<component> [...]]
 #       [SKIP_DEPENDENCY_HANDLING])
 #       [SKIP_PKG_CONFIG])
 #
@@ -65,6 +77,9 @@
 # the component that is searched for first (note that components are searched
 # for in the order they are passed to the macro).
 
+# FIXME: we should actually set proper traditional variables, because it can
+#        be convenient to use them in the link interface of exported libraries
+
 #=============================================================================
 # Copyright 2014 Alex Merry <alex.merry@kde.org>
 #
diff --git a/modules/ECMGenerateHeaders.cmake b/modules/ECMGenerateHeaders.cmake
index 739c2117..bac50869 100644
--- a/modules/ECMGenerateHeaders.cmake
+++ b/modules/ECMGenerateHeaders.cmake
@@ -1,26 +1,23 @@
-# - Function to generate forward includes for your project
-# This module provides the function ECM_GENERATE_HEADERS
+#.rst:
+# ECMGenerateHeaders
+# ------------------
 #
-# The ECM_GENERATE_HEADERS function is used to generate C/C++ forwarding header
-# files for your project.
+# Generate C/C++ CamelCase forwarding headers.
 #
-# To be more precise, there will be two kinds of headers being generated. Lowercase
-# and CamelCase, for convenience. That means that for a class named "ClassA" in a
-# module called "Module" we will get 2 different files: Module/ClassA and
-# module/classa.h. Both these files will be including a "classa.h" file that is
-# expected to be in the headers dir (see HEADERS_DIR argument below).
+# ::
 #
-# ECM_GENERATE_HEADERS(camelcase_headers_var
-#     HEADER_NAMES ClassA [ClassB [...]]
-#     [OUTPUT_DIR output_dir]
-#     [PREFIX prefix]
-#     [REQUIRED_HEADERS variable]
-#     [RELATIVE relative_path])
+#   ecm_generate_headers(<camelcase_headers_var>
+#       HEADER_NAMES <CamelCaseHeader> [<CamelCaseHeader> [...]]
+#       [OUTPUT_DIR <output_dir>]
+#       [PREFIX <prefix>]
+#       [REQUIRED_HEADERS <variable>]
+#       [RELATIVE <relative_path>])
 #
-# The paths to the generated CamelCase headers will be appended to
-# camelcase_headers_var.
-#
-# HEADER_NAMES lists the generated CamelCase header names.
+# For each CamelCase header name passed to HEADER_NAMES, a file of that name
+# will be generated that will include a lowercased version with ``.h`` appended.
+# For example, the header ``ClassA`` will include ``classa.h``.  The file
+# locations of these generated headers will be stored in
+# <camelcase_headers_var>.
 #
 # PREFIX places the headers in subdirectories.  This should be a CamelCase name
 # like KParts, which will cause the CamelCase headers to be placed in the KParts
@@ -30,67 +27,81 @@
 # used before installation, as long as the include_directories are set
 # appropriately.
 #
-# The OUTPUT_DIR argument specifies where the files will be generated; this
-# should be within the build directory. By default, CMAKE_CURRENT_BINARY_DIR
-# will be used.  This option can be used to avoid file conflicts.
+# OUTPUT_DIR specifies where the files will be generated; this should be within
+# the build directory. By default, ``${CMAKE_CURRENT_BINARY_DIR}`` will be used.
+# This option can be used to avoid file conflicts.
 #
-# The REQUIRED_HEADERS argument specifies an output variable name where all the
-# required headers will be appended so that they can be installed together with
-# the generated ones.  This is mostly intended as a convenience so that adding a
-# new header to a project only requires specifying the CamelCase variant in the
+# REQUIRED_HEADERS specifies an output variable name where all the required
+# headers will be appended so that they can be installed together with the
+# generated ones.  This is mostly intended as a convenience so that adding a new
+# header to a project only requires specifying the CamelCase variant in the
 # CMakeLists.txt file; the lowercase variant will then be added to this
 # variable.
 #
 # The RELATIVE argument indicates where the lowercase headers can be found
 # relative to CMAKE_CURRENT_SOURCE_DIR.  It does not affect the generated
-# CamelCase files, but ECM_GENERATE_HEADERS uses it when checking that the
+# CamelCase files, but ecm_generate_headers() uses it when checking that the
 # lowercase header exists, and to generate lowercase forwarding headers when
 # PREFIX is set.
 #
 # To allow other parts of the source distribution (eg: tests) to use the
 # generated headers before installation, it may be desirable to set the
 # INCLUDE_DIRECTORIES property for the library target to output_dir.  For
-# example, if output_dir is CMAKE_CURRENT_BINARY_DIR (the default), you could do
-#   target_include_directories(MyLib
-#       PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
+# example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you could do
+#
+# .. code-block:: cmake
+#
+#   target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
 #
 # Example usage (without PREFIX):
-# ecm_generate_headers(
-#     MyLib_FORWARDING_HEADERS
-#     HEADERS
-#         MLFoo
-#         MLBar
-#         # etc
-#     REQUIRED_HEADERS MyLib_HEADERS
-# )
-# install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
-#         DESTINATION ${CMAKE_INSTALL_PREFIX}/include
-#         COMPONENT Devel)
 #
-# Example usage (with PREFIX):
-# ecm_generate_headers(
-#     MyLib_FORWARDING_HEADERS
-#     HEADERS
-#         Foo
-#         Bar
-#         # etc
-#     PREFIX MyLib
-#     REQUIRED_HEADERS MyLib_HEADERS
-# )
-# install(FILES ${MyLib_FORWARDING_HEADERS}
-#         DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
-#         COMPONENT Devel)
-# install(FILES ${MyLib_HEADERS}
-#         DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
-#         COMPONENT Devel)
+# .. code-block:: cmake
 #
+#   ecm_generate_headers(
+#       MyLib_FORWARDING_HEADERS
+#       HEADERS
+#           MLFoo
+#           MLBar
+#           # etc
+#       REQUIRED_HEADERS MyLib_HEADERS
+#   )
+#   install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
+#           DESTINATION ${CMAKE_INSTALL_PREFIX}/include
+#           COMPONENT Devel)
 #
+# Example usage (with PREFIX):
+#
+# .. code-block:: cmake
+#
+#   ecm_generate_headers(
+#       MyLib_FORWARDING_HEADERS
+#       HEADERS
+#           Foo
+#           Bar
+#           # etc
+#       PREFIX MyLib
+#       REQUIRED_HEADERS MyLib_HEADERS
+#   )
+#   install(FILES ${MyLib_FORWARDING_HEADERS}
+#           DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
+#           COMPONENT Devel)
+#   install(FILES ${MyLib_HEADERS}
+#           DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
+#           COMPONENT Devel)
+
+#=============================================================================
 # Copyright 2013 Aleix Pol Gonzalez <aleixpol@blue-systems.com>
 # Copyright 2014 Alex Merry <alex.merry@kdemail.net>
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
 include(CMakeParseArguments)
 
diff --git a/modules/ECMGeneratePriFile.cmake b/modules/ECMGeneratePriFile.cmake
index d39a9f96..bff2961f 100644
--- a/modules/ECMGeneratePriFile.cmake
+++ b/modules/ECMGeneratePriFile.cmake
@@ -1,33 +1,81 @@
-# This file provides the function ecm_generate_pri_file().
-# ECM_GENERATE_PRI_FILE() creates a .pri file for a library so that qmake-based
-# apps can more easily use the library.
-# It also sets ECM_MKSPECS_INSTALL_DIR as the directory to install the .pri file to.
+#.rst:
+# ECMGeneratePriFile
+# ------------------
 #
-# Requirement: ${PROJECT_VERSION_STRING} must be set before ecm_generate_pri_file.
-# This is usually done by calling ecm_setup_version, which sets it.
+# Generate a ``.pri`` file for the benefit of qmake-based projects.
 #
-# Syntax:
-#   ecm_generate_pri_file(BASE_NAME baseName
-#                         LIB_NAME libName
-#                         [DEPS "dep1 dep2"]
-#                         [FILENAME_VAR filename_variable] )
+# As well as the function below, this module creates the cache variable
+# ``ECM_MKSPECS_INSTALL_DIR`` and sets the default value to ``mkspecs/modules``.
+# This assumes Qt and the current project are both installed to the same
+# non-system prefix.  Packagers who use ``-DCMAKE_INSTALL_PREFIX=/usr`` will
+# certainly want to set ``ECM_MKSPECS_INSTALL_DIR`` to something like
+# ``share/qt5/mkspecs/modules``.
 #
-# * baseName is the name which .pro files will use to refer to the library, i.e. the public name, like KArchive.
-# * libName is the name of the actual library to link to, i.e. the first argument to add_library().
-# * the deps are a space-separated list of base names of other libraries. Use core, widgets, etc. for Qt libs.
-# * filename_variable is the name of a variable, which will be set to contain the path of the .pri file to install
+# The main thing is that this should be the ``modules`` subdirectory of either
+# the default qmake ``mkspecs`` directory or of a directory that will be in the
+# ``$QMAKEPATH`` environment variable when qmake is run.
+#
+# ::
+#
+#   ecm_generate_pri_file(BASE_NAME <baseName>
+#                         LIB_NAME <libName>
+#                         [DEPS "<dep> [<dep> [...]]"]
+#                         [FILENAME_VAR <filename_variable>])
+#
+# If your CMake project produces a Qt-based library, you may expect there to be
+# applications that wish to use it that use a qmake-based build system, rather
+# than a CMake-based one.  Creating a ``.pri`` file will make use of your
+# library convenient for them, in much the same way that CMake config files make
+# things convenient for CMake-based applications.
+#
+# ecm_generate_pri_file() generates just such a file.  It depends on a few
+# variables being set:
+#
+# * ``PROJECT_VERSION_STRING``: typically set by :module:`ECMSetupVersion`,
+#   although the project() command in CMake 3.0.0 and later can also set this.
+# * ``INCLUDE_INSTALL_DIR``: this must be relative to ``CMAKE_INSTALL_PREFIX``,
+#   and includes are assumed to be install in the <baseName> subdirectory.
+# * ``LIB_INSTALL_DIR``: this must be relative to ``CMAKE_INSTALL_PREFIX``.
+#
+# BASE_NAME specifies the name qmake project (.pro) files should use to refer to
+# the library (eg: KArchive).  LIB_NAME is the name of the actual library to
+# link to (ie: the first argument to add_library()).  DEPS is a space-separated
+# list of the base names of other libraries (for Qt libraries, use the same
+# names you use with the ``QT`` variable in a qmake project file, such as "core"
+# for QtCore).  FILENAME_VAR specifies the name of a variable to store the path
+# to the generated file in.
 #
 # Example usage:
-#   ecm_generate_pri_file(BASE_NAME KArchive LIB_NAME KF5KArchive DEPS "core" FILENAME_VAR PRI_FILENAME)
-#   install(FILES ${PRI_FILENAME} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
 #
-# Copyright (c) 2014, David Faure <faure@kde.org>
+# .. code-block:: cmake
+#
+#   ecm_generate_pri_file(
+#       BASE_NAME KArchive
+#       LIB_NAME KF5KArchive
+#       DEPS "core"
+#       FILENAME_VAR pri_filename
+#   )
+#   install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
+#
+# A qmake-based project that wished to use this would then do::
+#
+#   QT += KArchive
+#
+# in their ``.pro`` file.
+
+#=============================================================================
+# Copyright 2014 David Faure <faure@kde.org>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
-# This default value makes "installing qt and this lib into the same prefix" work out of the box.
-# Packagers who use -DCMAKE_INSTALL_PREFIX=/usr will certainly want to set ECM_MKSPECS_INSTALL_DIR to something like share/qt5/mkspecs/modules
 set(ECM_MKSPECS_INSTALL_DIR mkspecs/modules CACHE PATH "The directory where mkspecs will be installed to.")
 
 function(ECM_GENERATE_PRI_FILE)
@@ -58,6 +106,8 @@ function(ECM_GENERATE_PRI_FILE)
   set(PRI_TARGET_BASENAME ${EGPF_BASE_NAME})
   set(PRI_TARGET_LIBNAME ${EGPF_LIB_NAME})
   set(PRI_TARGET_QTDEPS ${EGPF_DEPS})
+  # FIXME: Default value for INCLUDE_INSTALL_DIR, argument to override?
+  #        What about absolute paths?
   set(PRI_TARGET_INCLUDES "${CMAKE_INSTALL_PREFIX}/${INCLUDE_INSTALL_DIR}/${PRI_TARGET_BASENAME}")
   set(PRI_TARGET_DEFINES "")
 
@@ -66,6 +116,8 @@ function(ECM_GENERATE_PRI_FILE)
      set(${EGPF_FILENAME_VAR} ${PRI_FILENAME} PARENT_SCOPE)
   endif()
 
+  # FIXME: Default value for LIB_INSTALL_DIR, argument to override?
+  #        What about absolute paths?
   file(GENERATE
      OUTPUT ${PRI_FILENAME}
      CONTENT
diff --git a/modules/ECMInstallIcons.cmake b/modules/ECMInstallIcons.cmake
index e6d2adef..d83003ba 100644
--- a/modules/ECMInstallIcons.cmake
+++ b/modules/ECMInstallIcons.cmake
@@ -1,35 +1,56 @@
-# - Function for installing icons
-# This module provides the function ECM_INSTALL_ICONS().
-
-# ECM_INSTALL_ICONS installs all icons in the current path that
-# match a specific file naming convention into into the directory provided
-# following the Freedesktop.org icon naming spec
-# http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
-
-# The filenames of the icons in the directory must be in the following format
-# in order to be installed
-# themeSize-Group-name.extension
-
-# The following file extensions are supported
-# .png
-# .mng
-# .svgz
-
-# Where the theme is one of:
-# "hi" for hicolor
-# "lo" for locolor
-# "cr" for the crystal icon theme
-# "ox" for the oxygen icon theme
-
-# Size refers to the size of one dimension of the icon
-# Typically, 16, 22, 32, 48, 64, 128 or 256
-# For svgz files the size should be set to "sc"
-
-# For example the file
-# hi22-action-menu_new.png
-# would be installed into
-# PREFIX/hicolor/22x22/actions/menu_new.png
-
+#.rst:
+# ECMInstallIcons
+# ---------------
+#
+# Installs icons, sorting them into the correct directories according to the
+# FreeDesktop.org icon naming specification.
+#
+# ::
+#
+#   ecm_install_icons(<icon_install_dir> [<l10n_code>])
+#
+# Installs all icons found in ``CMAKE_CURRENT_SOURCE_DIR`` to the correct
+# subdirectory of ``<icon_install_dir>``.  ``<icon_install_dir>`` should
+# typically be something like ``share/icons``, although users of the
+# :kde-module:`KDEInstallDirs` module would normally do
+#
+# .. code-block:: cmake
+#
+#   ecm_install_icons(${ICON_INSTALL_DIR})
+#
+# The icons must be named in the form::
+#
+#   <theme><size>-<group>-<name>.<ext>
+#
+# where ``<theme>`` is one of
+# * ``hi`` for hicolor
+# * ``lo`` for locolor
+# * ``cr`` for the Crystal icon theme
+# * ``ox`` for the Oxygen icon theme
+#
+# ``<size>`` is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or 256)
+# or ``sc`` for scalable (SVG) files, ``<group>`` is one of the standard
+# FreeDesktop.org icon groups (actions, animations, apps, categories, devices,
+# emblems, emotes, intl, mimetypes, places, status) and ``<ext>`` is one of
+# ``.png``, ``.mng`` or ``.svgz``.
+#
+# For example the file ``hi22-action-menu_new.png`` would be installed into
+# ``<icon_install_dir>/hicolor/22x22/actions/menu_new.png``
+
+#=============================================================================
+# Copyright 2013 David Edmundson <kde@davidedmundson.co.uk>
+# Copyright 2008 Chusslove Illich <caslav.ilic@gmx.net>
+# Copyright 2006 Alex Neundorf <neundorf@kde.org>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
+#
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
 
 # a "map" of short type names to the directories
@@ -47,6 +68,8 @@ set(_ECM_ICON_GROUP_emotes     "emotes")
 set(_ECM_ICON_GROUP_animations "animations")
 set(_ECM_ICON_GROUP_intl       "intl")
 
+# FIXME: this is too KDE-specific; we should keep this map for compatibility,
+#        but get users to specify the full theme name
 # a "map" of short theme names to the theme directory
 set(_ECM_ICON_THEME_ox "oxygen")
 set(_ECM_ICON_THEME_cr "crystalsvg")
@@ -73,6 +96,7 @@ macro (ECM_INSTALL_ICONS _defaultpath )
       set(_group "${CMAKE_MATCH_3}")
       set(_name  "${CMAKE_MATCH_4}")
 
+      # FIXME: don't use map
       set(_theme_GROUP ${_ECM_ICON_THEME_${_type}})
       if( _theme_GROUP)
          _ECM_ADD_ICON_INSTALL_RULE(${CMAKE_CURRENT_BINARY_DIR}/install_icons.cmake
@@ -127,6 +151,7 @@ macro (_ECM_ADD_ICON_INSTALL_RULE _install_SCRIPT _install_PATH _group _orig_NAM
    if (NOT ${_group} STREQUAL ${_install_NAME} )
       set(_icon_GROUP  ${_ECM_ICON_GROUP_${_group}})
       if(NOT _icon_GROUP)
+         # FIXME: print warning if not in map (and not "actions")
          set(_icon_GROUP "actions")
       endif(NOT _icon_GROUP)
 #      message(STATUS "icon: ${_current_ICON} size: ${_size} group: ${_group} name: ${_name} l10n: ${_l10n_SUBDIR}")
@@ -146,4 +171,4 @@ macro (ECM_UPDATE_ICONCACHE)
         file(REMOVE \"${ICON_INSTALL_DIR}/hicolor/temp.txt\")
     endif (NOT DESTDIR_VALUE)
     ")
-endmacro (ECM_UPDATE_ICONCACHE)
\ No newline at end of file
+endmacro (ECM_UPDATE_ICONCACHE)
diff --git a/modules/ECMMarkAsTest.cmake b/modules/ECMMarkAsTest.cmake
index e20bfbfe..24b8cfc7 100644
--- a/modules/ECMMarkAsTest.cmake
+++ b/modules/ECMMarkAsTest.cmake
@@ -1,15 +1,32 @@
-# - Function for marking targets as being only for testing
-# This module provides the function ECM_MARK_AS_TEST().
+#.rst:
+# ECMMarkAsTest
+# -------------
 #
-# The ECM_MARK_AS_TEST function is used to indicate that a target should only
-# be built if the BUILD_TESTING option (provided by CTest) is enabled.
+# Marks a target as only being required for tests.
 #
-# ECM_MARK_AS_TEST( target1 target2 ... targetN )
+# ::
 #
-# If BUILD_TESTING is False, then targets marked as tests are excluded from
-# the ALL target. They are all part of the 'buildtests' target though, so
-# even if building with BUILD_TESTING set to False, it is possible to build
-# all tests by invoking the 'buildtests' target.
+#   ecm_mark_as_test(<target1> [<target2> [...]])
+#
+# This will cause the specified targets to not be built unless either
+# BUILD_TESTING is set to ON or the user invokes the ``buildtests`` target.
+#
+# BUILD_TESTING is created as a cache variable by the CTest module and by the
+# :kde-module:`KDECMakeSettings` module.
+
+#=============================================================================
+# Copyright 2012 Stephen Kelly <steveire@gmail.com>
+# Copyright 2012 Alex Neundorf <neundorf@kde.org>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
+#
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
 if (NOT BUILD_TESTING)
   if(NOT TARGET buildtests)
diff --git a/modules/ECMMarkNonGuiExecutable.cmake b/modules/ECMMarkNonGuiExecutable.cmake
index 3c199ab5..9b680216 100644
--- a/modules/ECMMarkNonGuiExecutable.cmake
+++ b/modules/ECMMarkNonGuiExecutable.cmake
@@ -1,11 +1,29 @@
-# - Function for marking executables as being non-gui
-# This module provides the function ECM_MARK_NONGUI_EXECUTABLE().
+#.rst:
+# ECMMarkNonGuiExecutable
+# -----------------------
 #
-# The ECM_MARK_NONGUI_EXECUTABLE function is used to indicate that an executable
-# target should not be part of a MACOSX_BUNDLE, and should not be a WIN32_EXECUTABLE.
+# Marks an executable target as not being a GUI application.
 #
-# ECM_MARK_NONGUI_EXECUTABLE( target1 target2 ... targetN )
+# ::
 #
+#   ecm_mark_nongui_executable(<target1> [<target2> [...]])
+#
+# This will indicate to CMake that the specified targets should not be included
+# in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs.  On platforms other
+# than MacOS X or Windows, this will have no effect.
+
+#=============================================================================
+# Copyright 2012 Stephen Kelly <steveire@gmail.com>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
+#
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
 function(ecm_mark_nongui_executable)
   foreach(_target ${ARGN})
diff --git a/modules/ECMOptionalAddSubdirectory.cmake b/modules/ECMOptionalAddSubdirectory.cmake
index c7931f0c..6cbafa2d 100644
--- a/modules/ECMOptionalAddSubdirectory.cmake
+++ b/modules/ECMOptionalAddSubdirectory.cmake
@@ -1,28 +1,42 @@
-# - ECM_OPTIONAL_ADD_SUBDIRECTORY() combines ADD_SUBDIRECTORY() with an OPTION()
-#
-# ECM_OPTIONAL_ADD_SUBDIRECTORY(<dir>)
-#
-# If you use ECM_OPTIONAL_ADD_SUBDIRECTORY() instead of ADD_SUBDIRECTORY(),
-# this will have two effects
-#
-# 1 - CMake will not complain if the directory doesn't exist
-#     This makes sense if you want to distribute just one of the subdirs
-#     in a source package, e.g. just one of the subdirs in kdeextragear.
-# 2 - If the directory exists, it will offer an option to skip the
-#     subdirectory.
-#     This is useful if you want to compile only a subset of all
-#     directories.
-#
-# If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to TRUE
-# for the first CMake run on the project, all optional subdirectories will be disabled
-# by default (but can of course be enabled via the respective options).
-# E.g. the following will disable all optional subdirectories except the one named "kcalc":
-#   $ cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_kcalc=TRUE <srcdir>
+#.rst:
+# ECMOptionalAddSubdirectory
+# --------------------------
+#
+# Make subdiretories optional.
+#
+# ::
+#
+#   ecm_optional_add_subdirectory(<dir>)
+#
+# This behaves like add_subdirectory(), except that it does not complain if the
+# directory does not exist.  Additionally, if the directory does exist, it
+# creates an option to allow the user to skip it.
+#
+# This is useful for "meta-projects" that combine several mostly-independent
+# sub-projects.
+#
+# If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to TRUE for
+# the first CMake run on the project, all optional subdirectories will be
+# disabled by default (but can of course be enabled via the respective options).
+# For example, the following will disable all optional subdirectories except the
+# one named "foo":
+#
+# .. code-block:: sh
+#
+#   cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
 
-# Copyright (c) 2007, Alexander Neundorf, <neundorf@kde.org>
+#=============================================================================
+# Copyright 2007 Alexander Neundorf <neundorf@kde.org>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
 
 function(ECM_OPTIONAL_ADD_SUBDIRECTORY _dir)
diff --git a/modules/ECMPackageConfigHelpers.cmake b/modules/ECMPackageConfigHelpers.cmake
index 2ccf32f6..da65c3ea 100644
--- a/modules/ECMPackageConfigHelpers.cmake
+++ b/modules/ECMPackageConfigHelpers.cmake
@@ -1,11 +1,28 @@
-# - ECM_CONFIGURE_PACKAGE_CONFIG_FILE(), WRITE_BASIC_PACKAGE_VERSION_FILE()
+#.rst:
+# ECMPackageConfigHelpers
+# -----------------------
 #
-# WRITE_BASIC_PACKAGE_VERSION_FILE() is actually just the macro from the
-# CMakePackageConfigHelpers module.
+# Helper macros for generating CMake package config files.
 #
-# ECM_CONFIGURE_PACKAGE_CONFIG_FILE() behaves like
-# CONFIGURE_PACKAGE_CONFIG_FILE() from CMake 2.8.12, except that it adds an
-# extra helper macro: find_dependency().
+# ``write_basic_package_version_file()`` is the same as the one provided by the
+# CMakePackageConfigHelpers module in CMake; see that module's documentation for
+# more information.
+#
+# ::
+#
+#   ecm_configure_package_config_file(<input> <output>
+#       INSTALL_DESTINATION <path>
+#       [PATH_VARS <var1> [<var2> [...]]
+#       [NO_SET_AND_CHECK_MACRO]
+#       [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
+#
+#
+# This behaves in the same way as configure_package_config_file() from CMake
+# 2.8.12, except that it adds an extra helper macro: find_dependency().
+#
+# ::
+#
+#   find_dependency(<dep> [<version> [EXACT]])
 #
 # find_dependency() should be used instead of find_package() to find package
 # dependencies.  It forwards the correct parameters for EXACT, QUIET and
@@ -17,10 +34,23 @@
 # module directly.
 #
 # CMake 3.0.0 will include a CMakeFindDependencyMacro module that will provide
-# the find_dependency macro (which you can include() in your *Config.cmake
+# the find_dependency() macro (which you can include() in your package config
 # file), so this file is only useful for projects whose minimum required version
 # is 2.8.12.
+
+#=============================================================================
+# Copyright 2014 Alex Merry <alex.merry@kdemail.net>
+# Copyright 2013 Stephen Kelly <steveire@gmail.com>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
 include(${CMAKE_ROOT}/Modules/CMakePackageConfigHelpers.cmake)
 
diff --git a/modules/ECMSetupVersion.cmake b/modules/ECMSetupVersion.cmake
index 3a8defd8..3ae6fa8f 100644
--- a/modules/ECMSetupVersion.cmake
+++ b/modules/ECMSetupVersion.cmake
@@ -1,49 +1,70 @@
-# This file provides the function ecm_setup_version().
-# ECM_SETUP_VERSION() bundles three things which are usually done for versioned libraries:
-#  - it sets a set of version variables
-#  - optionally it creates a C version header file, which can then be installed along with the library
-#  - optionally it creates a CMake package version file, which can then be installed along with a
-#    CMake package Config.cmake file
+#.rst:
+# ECMSetupVersion
+# ---------------
+#
+# Handle library version information.
+#
+# ::
 #
 #   ecm_setup_version(<version>
-#                     VARIABLE_PREFIX prefix
+#                     VARIABLE_PREFIX <prefix>
 #                     [SOVERSION <soversion>]
-#                     [VERSION_HEADER filename]
-#                     [PACKAGE_VERSION_FILE filename] )
+#                     [VERSION_HEADER <filename>]
+#                     [PACKAGE_VERSION_FILE <filename>] )
+#
+# This parses a version string and sets up a standard set of version variables.
+# It can optionally also create a C version header file and a CMake package
+# version file to install along with the library.
 #
+# If the ``<version>`` argument is of the form ``<major>.<minor>.<patch>``
+# (or ``<major>.<minor>.<patch>.<tweak>``), The following CMake variables are
+# set::
 #
-# ecm_setup_version() sets the following CMake variables
-#    <prefix>_VERSION_MAJOR = <version_major_component>
-#    <prefix>_VERSION_MINOR = <version_minor_component>
-#    <prefix>_VERSION_PATCH = <version_patch_component>
-#    <prefix>_VERSION_STRING = <major>.<minor>.<patch>
-#    <prefix>_SOVERSION is set to <major> if <soversion> has not been specified.
+#   <prefix>_VERSION_MAJOR  - <major>
+#   <prefix>_VERSION_MINOR  - <minor>
+#   <prefix>_VERSION_PATCH  - <patch>
+#   <prefix>_VERSION_STRING - <version>
+#   <prefix>_SOVERSION      - <soversion>, or <major> if SOVERSION was not given
+#   PROJECT_VERSION_MAJOR   - <major>
+#   PROJECT_VERSION_MINOR   - <minor>
+#   PROJECT_VERSION_PATCH   - <patch>
+#   PROJECT_VERSION_STRING  - <version>
 #
-# It also sets PROJECT_VERSION_MAJOR, PROJECT_VERSION_MINOR, PROJECT_VERSION_PATCH and
-# PROJECT_VERSION_STRING, for easier use with configure_file and file(GENERATE).
+# If the VERSION_HEADER option is used, a simple C header is generated with the
+# given filename. If filename is a relative path, it is interpreted as relative
+# to CMAKE_CURRENT_BINARY_DIR.  The generated header contains the following
+# macros::
 #
-# If the VERSION_HEADER option is used, a simple C header is generated with the given
-# filename. If filename is a relative path, it is interpreted as relative to
-# CMAKE_CURRENT_BINARY_DIR.
-# The generated header contains the following macros:
-#    <prefix>_VERSION_MAJOR
-#    <prefix>_VERSION_MINOR
-#    <prefix>_VERSION_PATCH
-#    <prefix>_VERSION_STRING - containing the full version number as a C string
-#    <prefix>_VERSION - containing the full version combined into one integer
+#    <prefix>_VERSION_MAJOR  - <major> as an integer
+#    <prefix>_VERSION_MINOR  - <minor> as an integer
+#    <prefix>_VERSION_PATCH  - <patch> as an integer
+#    <prefix>_VERSION_STRING - <version> as a C string
+#    <prefix>_VERSION        - the version as an integer
+#
+# ``<prefix>_VERSION`` has ``<patch>`` in the bottom 8 bits, ``<minor>`` in the
+# next 8 bits and ``<major>`` in the remaining bits.  Note that ``<patch>`` and
+# ``<minor>`` must be less than 256.
 #
 # If the PACKAGE_VERSION_FILE option is used, a simple CMake package version
-# file is created using the write_basic_package_version_file() macro coming
-# with CMake. It should be installed along the Config.cmake file of the library
-# into the same directory where it can be found by find_package().
-# Also here, if the given filename is a relative path, it is interpreted as
-# relative to CMAKE_CURRENT_BINARY_DIR.
+# file is created using the write_basic_package_version_file() macro provided by
+# CMake. It should be installed in the same location as the Config.cmake file of
+# the library so that it can be found by find_package().  If the filename is a
+# relative path, it is interpreted as relative to CMAKE_CURRENT_BINARY_DIR.
 
-# Copyright (c) 2012, Alexander Neundorf, <neundorf@kde.org>
+#=============================================================================
+# Copyright 2012 Alexander Neundorf <neundorf@kde.org>
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
-
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
+#
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
+
+# FIXME: Figure out how this should interact with CMP0048 in CMake 3.0.0
 
 include(CMakePackageConfigHelpers)
 
diff --git a/modules/ECMUseFindModules.cmake b/modules/ECMUseFindModules.cmake
index 6bf3c904..25f42666 100644
--- a/modules/ECMUseFindModules.cmake
+++ b/modules/ECMUseFindModules.cmake
@@ -1,40 +1,62 @@
-# - Selectively use some of the Find-modules provided by extra-cmake-modules (ECM)
+#.rst:
+# ECMUseFindModules
+# -----------------
 #
-# ECM_USE_FIND_MODULES(DIR <dir> MODULES module1.cmake module2.cmake .. moduleN.cmake [NO_OVERRIDE] )
+# Selectively use some of the find modules provided by extra-cmake-modules.
 #
-# This macro is automatically available once extra-cmake-modules has been found, so it is not
-# necessary to include(ECMUseFindModules) explicitly.
+# This module is automatically available once extra-cmake-modules has been
+# found, so it is not necessary to ``include(ECMUseFindModules)`` explicitly.
 #
-# Use this macro instead of simply adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH
-# if you want to use only a subset or some specific find-modules coming with extra-cmake-modules.
-# The given find-modules will be copied to the given directory. This directory should then be added
-# to CMAKE_MODULE_PATH. The given modules override modules of the same name coming with CMake, except
-# if the NO_OVERRIDE option has been used.
+# ::
 #
-#   DIR <dir> : the selected module files will be copied to that directory. The directory should be
-#               located somewhere inside ${CMAKE_BINARY_DIR}. It should then be added to CMAKE_MODULE_PATH .
-#               The directory is created if it does not exist yet.
-#   MODULES   : the list of find-modules to be used from extra-cmake-modules
-#   NO_OVERRIDE: if used, the given modules will only be used if they do not exist in the currently used
-#                CMake version
+#   ecm_use_find_modules(DIR <dir>
+#                        MODULES module1.cmake [module2.cmake [...]]
+#                        [NO_OVERRIDE])
+#
+# This allows selective use of the find modules provided by ECM, including
+# deferring to CMake's versions of those modules if it has them.  Rather than
+# adding ``${ECM_FIND_MODULE_DIR}`` to ``CMAKE_MODULE_PATH``, you use
+# ecm_use_find_modules() to copy the modules you want to a local (build)
+# directory, and add that to ``CMAKE_MODULE_PATH``.
+#
+# The find modules given to MODULES will be copied to the directory given by DIR
+# (which should be located in ``${CMAKE_BINARY_DIR}`` and added to
+# ``CMAKE_MODULE_PATH``).  If NO_OVERRIDE is given, only modules not also
+# provided by CMake will be copied.
 #
 # Example:
-#   find_package(ECM 0.0.4 REQUIRED)
-#   ecm_use_find_modules(DIR ${CMAKE_BINARY_DIR}/cmake/ Modules FindBlueZ.cmake NO_OVERRIDE )
-#   set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake/ )
 #
-# This example will make FindBlueZ.cmake available in your project, but only as long as it
-# is not yet part of CMake. The file will be copied into ${CMAKE_BINARY_DIR}/cmake/, and then this
-# directory is added to CMAKE_MODULE_PATH.
+# .. code-block:: cmake
+#
+#   find_package(ECM REQUIRED)
+#   ecm_use_find_modules(
+#       DIR ${CMAKE_BINARY_DIR}/cmake
+#       MODULES FindEGL.cmake
+#       NO_OVERRIDE
+#   )
+#   set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
+#
+# This example will make ``FindEGL.cmake`` available in your project, but only
+# as long as it is not yet part of CMake. Calls to ``find_package(EGL)`` will
+# then make use of this copied module (or the CMake module if it exists).
+#
+# Another possible use for this macro is to take copies of find modules that can
+# be installed along with config files if they are required as a dependency (for
+# example, if targets provided by the find module are in the link interface of a
+# library).
 
+#=============================================================================
 # Copyright 2011 Alexander Neundorf <neundorf@kde.org>
 #
 # Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
 # This software is distributed WITHOUT ANY WARRANTY; without even the
 # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 # See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
 include(CMakeParseArguments)