Merge topic 'patch-CTestCoverageCollectGCOV'

45db842032 CTestCoverageCollectGCOV: Extend documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10797

Modules/CTestCoverageCollectGCOV.cmake

@@ -7,67 +7,82 @@ CTestCoverageCollectGCOV
 
 .. versionadded:: 3.2
 
-This module provides the ``ctest_coverage_collect_gcov()`` function.
+This module is intended for use in CTest dashboard scripts and provides a
+command to generate a tarball containing code coverage reports.
 
-This function runs ``gcov`` on all ``.gcda`` files found in the binary tree
-and packages the resulting ``.gcov`` files into a tar file.
-This tarball also contains the following:
+Load this module in a CTest script with:
 
-* *data.json* defines the source and build directories for use by CDash.
-* *Labels.json* indicates any :prop_sf:`LABELS` that have been set on the
-  source files.
-* The *uncovered* directory holds any uncovered files found by
-  :variable:`CTEST_EXTRA_COVERAGE_GLOB`.
+.. code-block:: cmake
+
+  include(CTestCoverageCollectGCOV)
+
+Commands
+^^^^^^^^
 
-After generating this tar file, it can be sent to CDash for display with the
-:command:`ctest_submit(CDASH_UPLOAD)` command.
+This module provides the following command:
 
 .. command:: ctest_coverage_collect_gcov
 
+  Runs ``gcov`` and packages a tar file for CDash:
+
   .. code-block:: cmake
 
     ctest_coverage_collect_gcov(
-      TARBALL <tarfile>
-      [TARBALL_COMPRESSION <option>]
-      [SOURCE <source_dir>]
-      [BUILD <build_dir>]
-      [GCOV_COMMAND <gcov_command>]
+      TARBALL <tar-file>
+      [TARBALL_COMPRESSION <compression>]
+      [SOURCE <source-dir>]
+      [BUILD <build-dir>]
+      [GCOV_COMMAND <gcov-command>]
       [GCOV_OPTIONS <options>...]
       [GLOB]
       [DELETE]
       [QUIET]
     )
 
-  Run ``gcov`` and package a tar file for CDash.  The options are:
+  This command runs ``gcov`` on all ``.gcda`` files found in the binary tree
+  and packages the resulting ``.gcov`` files into a tar file, along with the
+  following:
+
+  * *data.json* file that defines the source and build directories for use
+    by CDash.
+  * *Labels.json* files that indicate any :prop_sf:`LABELS` that have been
+    set on the source files.
+  * The *uncovered* directory containing any uncovered files found by
+    :variable:`CTEST_EXTRA_COVERAGE_GLOB`.
+
+  The resulting tar file can be submitted to CDash for display using the
+  :command:`ctest_submit(CDASH_UPLOAD)` command.
+
+  The arguments are:
 
-  ``TARBALL <tarfile>``
+  ``TARBALL <tar-file>``
     Specify the location of the ``.tar`` file to be created for later
     upload to CDash.  Relative paths will be interpreted with respect
     to the top-level build directory.
 
-  ``TARBALL_COMPRESSION <option>``
+  ``TARBALL_COMPRESSION <compression>``
     .. versionadded:: 3.18
 
     Specify a compression algorithm for the
     ``TARBALL`` data file.  Using this option reduces the size of the data file
-    before it is submitted to CDash.  ``<option>`` must be one of ``GZIP``,
+    before it is submitted to CDash.  ``<compression>`` must be one of ``GZIP``,
     ``BZIP2``, ``XZ``, ``ZSTD``, ``FROM_EXT``, or an expression that CMake
-    evaluates as ``FALSE``. The default value is ``BZIP2``.
+    evaluates as ``FALSE``.  The default value is ``BZIP2``.
 
     If ``FROM_EXT`` is specified, the resulting file will be compressed based on
-    the file extension of the ``<tarfile>`` (i.e. ``.tar.gz`` will use ``GZIP``
+    the file extension of the ``<tar-file>`` (i.e. ``.tar.gz`` will use ``GZIP``
     compression). File extensions that will produce compressed output include
     ``.tar.gz``, ``.tgz``, ``.tar.bzip2``, ``.tbz``, ``.tar.xz``, and ``.txz``.
 
-  ``SOURCE <source_dir>``
+  ``SOURCE <source-dir>``
     Specify the top-level source directory for the build.
     Default is the value of :variable:`CTEST_SOURCE_DIRECTORY`.
 
-  ``BUILD <build_dir>``
+  ``BUILD <build-dir>``
     Specify the top-level build directory for the build.
     Default is the value of :variable:`CTEST_BINARY_DIRECTORY`.
 
-  ``GCOV_COMMAND <gcov_command>``
+  ``GCOV_COMMAND <gcov-command>``
     Specify the full path to the ``gcov`` command on the machine.
     Default is the value of :variable:`CTEST_COVERAGE_COMMAND`.
 
@@ -79,18 +94,18 @@ After generating this tar file, it can be sent to CDash for display with the
   ``GLOB``
     .. versionadded:: 3.6
 
-    Recursively search for ``.gcda`` files in ``<build_dir>`` rather than
+    Recursively search for ``.gcda`` files in ``<build-dir>`` rather than
     determining search locations by reading ``CMakeFiles/TargetDirectories.txt``
     (file generated by CMake at the generation phase).
 
   ``DELETE``
     .. versionadded:: 3.6
 
-    Delete coverage files after they've been packaged into the .tar.
+    Delete coverage files after they've been packaged into the ``.tar``.
 
   ``QUIET``
     Suppress non-error messages that otherwise would have been
-    printed out by this function.
+    printed out by this command.
 
   .. versionadded:: 3.3
     Added support for the :variable:`CTEST_CUSTOM_COVERAGE_EXCLUDE` variable.
@@ -102,6 +117,7 @@ Generating code coverage data packaged as a ``.tar.gz`` file in a
 :option:`ctest -S` script:
 
 .. code-block:: cmake
+  :caption: ``script.cmake``
 
   include(CTestCoverageCollectGCOV)