Add missing documentation.

Three modules (ECMCoverageOption, ECMEnableSanitizers and
ECMGeneratePkgConfigFile) were not being documented. This commit fixes
that situation.

6 files changed, 86 insertions, 70 deletions

diff --git a/docs/module/ECMCoverageOption.rst b/docs/module/ECMCoverageOption.rst
new file mode 100644
index 00000000..41bffd78
--- /dev/null
+++ b/docs/module/ECMCoverageOption.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMCoverageOption.cmake
diff --git a/docs/module/ECMEnableSanitizers.rst b/docs/module/ECMEnableSanitizers.rst
new file mode 100644
index 00000000..e25dd4f8
--- /dev/null
+++ b/docs/module/ECMEnableSanitizers.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMEnableSanitizers.cmake
diff --git a/docs/module/ECMGeneratePkgConfigFile.rst b/docs/module/ECMGeneratePkgConfigFile.rst
new file mode 100644
index 00000000..cd311f6b
--- /dev/null
+++ b/docs/module/ECMGeneratePkgConfigFile.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMGeneratePkgConfigFile.cmake
diff --git a/modules/ECMCoverageOption.cmake b/modules/ECMCoverageOption.cmake
index 4cfe6641..4c1db9de 100644
--- a/modules/ECMCoverageOption.cmake
+++ b/modules/ECMCoverageOption.cmake
@@ -2,15 +2,17 @@
 # ECMCoverageOption
 # --------------------
 #
-# Creates a BUILD_COVERAGE option, so the project can be built with code coverage
-# support.
+# Allow users to easily enable GCov code coverage support.
 #
-# ::
+# Code coverage allows you to check how much of your codebase is covered by
+# your tests. This module makes it easy to build with support for
+# `GCov <https://gcc.gnu.org/onlinedocs/gcc/Gcov.html>`_.
 #
-#   BUILD_COVERAGE
+# When this module is included, a ``BUILD_COVERAGE`` option is added (default
+# OFF). Turning this option on enables GCC's coverage instrumentation, and
+# links against ``libgcov``.
 #
-# If it's on, the project will be compiled with code coverage support, using
-# gcov. Otherwise, it will be built normally.
+# Note that this will probably break the build if you are not using GCC.
 #
 # Since 1.3.0.
 
diff --git a/modules/ECMEnableSanitizers.cmake b/modules/ECMEnableSanitizers.cmake
index 568fa397..d55b2525 100644
--- a/modules/ECMEnableSanitizers.cmake
+++ b/modules/ECMEnableSanitizers.cmake
@@ -2,9 +2,10 @@
 # ECMEnableSanitizers
 # -------------------
 #
-# Enable compiler sanitizer flags
+# Enable compiler sanitizer flags.
+#
+# The following sanitizers are supported:
 #
-# The following sanitizers are supported :
 # - Address Sanitizer
 # - Memory Sanitizer
 # - Thread Sanitizer
@@ -14,52 +15,56 @@
 # All of them are implemented in Clang, depending on your version, and
 # there is an work in progress in GCC, where some of them are currently
 # implemented.
-# This module will check your current compiler version to see if it support
-# the sanitizers that you want to enable
 #
-# How to use it ?
-# ---------------
-# This module is included in KDECompilerSettings. Therefore you don't have
-# to change your CMakeLists.txt
+# This module will check your current compiler version to see if it
+# supports the sanitizers that you want to enable
+#
+# Usage
+# =====
+#
+# Simply add::
+#
+#    include(ECMEnableSanitizers)
 #
-# It introduce a new cached variable :
-#       ECM_ENABLE_SANITIZERS
+# to your ``CMakeLists.txt``. Note that this module is included in
+# KDECompilerSettings, so projects using that module do not need to also
+# include this one.
+#
+# The sanitizers are not enabled by default. Instead, you must set
+# ``ECM_ENABLE_SANITIZERS`` (either in your ``CMakeLists.txt`` or on the
+# command line) to a semicolon-separated list of sanitizers you wish to enable.
+# The options are:
 #
-# which can take the following values :
 # - address
 # - memory
 # - thread
 # - leak
 # - undefined
 #
-# You can enable two sanitizers in the same build, depending on their
-# compatibility by separating each one with a semicolon :
-#       ECM_ENABLE_SANITIZERS='address;undefined'
+# The sanitizers "address", "memory" and "thread" are mutually exclusive.  You
+# cannot enable two of them in the same build.
 #
+# "leak" requires the  "address" sanitizer.
 #
-# The sanitizers `address`, `memory` and `thread` are mutually exclusive.
-# You cannot enable two of them in the same build.
+# .. note::
 #
-# `undefined` can be used with every other sanitizers
+#   To reduce the overhead induced by the instrumentation of the sanitizers, it
+#   is advised to enable compiler optimizations (``-O1`` or higher).
 #
-# `leak` can be enable with the  `address` sanitizer.
+# Example
+# =======
 #
-# Finally, to reduce the overhead induced by the instrumentation of the
-# sanitizers, it is advised to use -O1, or higher to improve the performances.
+# This is an example of usage::
 #
-# Example
-# -------
-# This is an example of usage :
-# mkdir _build
-# cd _build
-# cmake -DECM_ENABLE_SANITIZERS='address' ..
+#   mkdir build
+#   cd build
+#   cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
 #
-# If you want to use multiple sanitizers
+# .. note::
 #
-# cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
+#   Most of the sanitizers will require Clang. To enable it, use::
 #
-# => Most of the sanitizers will require Clang. To enable it, use :
-# -DCMAKE_CXX_COMPILER=clang++
+#     -DCMAKE_CXX_COMPILER=clang++
 #
 # Since 1.3.0.
 
diff --git a/modules/ECMGeneratePkgConfigFile.cmake b/modules/ECMGeneratePkgConfigFile.cmake
index 052dcb1e..eaef7b41 100644
--- a/modules/ECMGeneratePkgConfigFile.cmake
+++ b/modules/ECMGeneratePkgConfigFile.cmake
@@ -1,8 +1,11 @@
 #.rst:
 # ECMGeneratePkgConfigFile
-# ------------------
+# ------------------------
 #
-# Generate a ``.pc`` file for the benefit of autotools-based projects.
+# Generate a `pkg-config <http://www.freedesktop.org/wiki/Software/pkg-config/>`_
+# file for the benefit of
+# `autotools <http://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html>`_-based
+# projects.
 #
 # ::
 #
@@ -15,38 +18,41 @@
 #                         [DEFINES -D<variable=value>...]
 #                         [INSTALL])
 #
-# BASE_NAME is the name of the module. It's the name projects will use to find
-# the module.
-#
-# LIB_NAME is the name of the library that is being exported. If undefined, it
-# will default to the BASE_NAME. That means the LIB_NAME will be set as the name
-# field as well as the library to link to.
-#
-# FILENAME_VAR is specified with a variable name. This variable will receive the
-# location of the generated file will be set, within the build directory. This
-# way it can be used in case some processing is required. See also INSTALL.
-#
-# INCLUDE_INSTALL_DIR specifies where the includes will be installed. If it's not
-# specified, it will default to INSTALL_INCLUDEDIR, CMAKE_INSTALL_INCLUDEDIR or just
-# "include/" in case they are specified, with the BASE_NAME postfixed.
-#
-# LIB_INSTALL_DIR specifies where the library is being installed. If it's not
-# specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR or just
-# "lib/" in case they are specified.
-#
-# DEFINES is a list of preprocessor defines that it is recommended users of the
-# library pass to the compiler when using it.
-#
-# INSTALL will cause the module to be installed to the ``pkgconfig`` subdirectory
-# of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR cache variable is set
-# to something different. Note that the first call to ecm_generate_pkgconfig_file
-# with the INSTALL argument will cause ECM_PKGCONFIG_INSTALL_DIR to be set to the
-# cache, and will be used in any subsequent calls.
-#
-# To properly use this macro a version needs to be set. To retrieve it ``ECM_PKGCONFIG_INSTALL_DIR``
-# uses PROJECT_VERSION. To set it, use the project() command (only available since CMake 3.0) or the
-# ecm_setup_version() macro.
-#
+# ``BASE_NAME`` is the name of the module. It's the name projects will use to
+# find the module.
+#
+# ``LIB_NAME`` is the name of the library that is being exported. If undefined,
+# it will default to the ``BASE_NAME``. That means the ``LIB_NAME`` will be set
+# as the name field as well as the library to link to.
+#
+# ``FILENAME_VAR`` is specified with a variable name. This variable will
+# receive the location of the generated file will be set, within the build
+# directory. This way it can be used in case some processing is required. See
+# also ``INSTALL``.
+#
+# ``INCLUDE_INSTALL_DIR`` specifies where the includes will be installed. If
+# it's not specified, it will default to ``INSTALL_INCLUDEDIR``,
+# ``CMAKE_INSTALL_INCLUDEDIR`` or just "include/" in case they are specified,
+# with the BASE_NAME postfixed.
+#
+# ``LIB_INSTALL_DIR`` specifies where the library is being installed. If it's
+# not specified, it will default to ``LIB_INSTALL_DIR``,
+# ``CMAKE_INSTALL_LIBDIR`` or just "lib/" in case they are specified.
+#
+# ``DEFINES`` is a list of preprocessor defines that it is recommended users of
+# the library pass to the compiler when using it.
+#
+# ``INSTALL`` will cause the module to be installed to the ``pkgconfig``
+# subdirectory of ``LIB_INSTALL_DIR``, unless the ``ECM_PKGCONFIG_INSTALL_DIR``
+# cache variable is set to something different. Note that the first call to
+# ecm_generate_pkgconfig_file with the ``INSTALL`` argument will cause
+# ``ECM_PKGCONFIG_INSTALL_DIR`` to be set to the cache, and will be used in any
+# subsequent calls.
+#
+# To properly use this macro a version needs to be set. To retrieve it,
+# ``ECM_PKGCONFIG_INSTALL_DIR`` uses ``PROJECT_VERSION``. To set it, use the
+# project() command (only available since CMake 3.0) or the ecm_setup_version()
+# macro.
 #
 # Example usage:
 #