Help: Add remaining intro code blocks to modules

This is a follow-up to add intro code blocks to all remaining utility
and find modules.

Fixes: #26555

Modules/BundleUtilities.cmake

@@ -9,7 +9,7 @@ This module provides utility commands for assembling standalone,
 bundle-style applications with CMake, such as macOS ``.app`` bundles or
 similar directory-based application bundles on other operating systems.
 
-Load this module in CMake installation with:
+Load this module in a CMake installation with:
 
 .. code-block:: cmake
 

Modules/CMakeAddFortranSubdirectory.cmake

@@ -8,7 +8,7 @@ CMakeAddFortranSubdirectory
 This module provides a command to add a Fortran project located in a
 subdirectory.
 
-Load it in a CMake project with:
+Load this module in a CMake project with:
 
 .. code-block:: cmake
 

Modules/CMakeFindDependencyMacro.cmake

@@ -5,6 +5,26 @@
 CMakeFindDependencyMacro
 ------------------------
 
+This module provides a command implemented as a macro that finds dependency
+for a package.
+
+Load this module in a CMake package configuration file with:
+
+.. code-block:: cmake
+  :caption: ``FooConfig.cmake`` or ``foo-config.cmake``:
+
+  include(CMakeFindDependencyMacro)
+
+.. note::
+
+  This module is designed to be used in a :ref:`Package Configuration File
+  <Config File Packages>` (``<PackageName>Config.cmake``).
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
+
 .. command:: find_dependency
 
   The ``find_dependency()`` macro wraps a :command:`find_package` call for

Modules/CMakePackageConfigHelpers.cmake

@@ -5,9 +5,16 @@
 CMakePackageConfigHelpers
 -------------------------
 
-Helper functions for creating config files that can be included by other
+This module provides helper commands for creating :ref:`config files
+<Libraries providing Config-file packages>` that can be included by other
 projects to find and use a package.
 
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CMakePackageConfigHelpers)
+
 Generating a Package Configuration File
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Modules/CMakePrintSystemInformation.cmake

@@ -7,16 +7,27 @@ CMakePrintSystemInformation
 
 This module can be used for diagnostics to print system information.
 
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CMakePrintSystemInformation)
+
 Examples
 ^^^^^^^^
 
-Including this module in a project:
+For example, including this module in a project:
 
 .. code-block:: cmake
+  :caption: ``CMakeLists.txt``
+
+  project(Example)
+
+  # ...
 
   include(CMakePrintSystemInformation)
 
-prints various internal CMake variables.  For example::
+prints various CMake variables::
 
   CMAKE_SYSTEM is Linux-6.11.0-17-generic Linux 6.11.0-17-generic x86_64
   CMAKE_SYSTEM file is Platform/Linux

Modules/CMakePushCheckState.cmake

@@ -11,7 +11,7 @@ This module provides commands for managing the state of variables that influence
 how various CMake check commands (e.g., :command:`check_symbol_exists`, etc.)
 are performed.
 
-Load this module in CMake project with:
+Load this module in a CMake project with:
 
 .. code-block:: cmake
 

Modules/CPack.cmake

@@ -5,7 +5,13 @@
 CPack
 -----
 
-Configure generators for binary installers and source packages.
+This module configures generators for binary installers and source packages.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CPack)
 
 Introduction
 ^^^^^^^^^^^^

Modules/CPackComponent.cmake

@@ -5,7 +5,14 @@
 CPackComponent
 --------------
 
-Configure components for binary installers and source packages.
+This module provides commands to configure components for binary installers
+and source packages.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CPackComponent)
 
 .. only:: html
 
@@ -14,7 +21,7 @@ Configure components for binary installers and source packages.
 Introduction
 ^^^^^^^^^^^^
 
-This module is automatically included by :module:`CPack`.
+This module is also automatically included by :module:`CPack`.
 
 Certain binary installers (especially the graphical installers) generated
 by CPack allow users to select individual application *components* to install.

Modules/CPackIFW.cmake

@@ -11,6 +11,12 @@ This module looks for the location of the command-line utilities supplied with t
 `Qt Installer Framework <https://doc.qt.io/qtinstallerframework/index.html>`_
 (QtIFW).
 
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CPackIFW)
+
 The module also defines several commands to control the behavior of the
 :cpack_gen:`CPack IFW Generator`.
 

Modules/CPackIFWConfigureFile.cmake

@@ -7,9 +7,14 @@ CPackIFWConfigureFile
 
 .. versionadded:: 3.8
 
-The module defines :command:`configure_file` similar command to
+This module defines :command:`configure_file` similar command to
 configure file templates prepared in QtIFW/SDK/Creator style.
 
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CPackIFWConfigureFile)
 
 Commands
 ^^^^^^^^

Modules/CTestUseLaunchers.cmake

@@ -13,6 +13,12 @@ This module sets the ``RULE_LAUNCH_*`` global properties when the
 * :prop_gbl:`RULE_LAUNCH_CUSTOM`
 * :prop_gbl:`RULE_LAUNCH_LINK`
 
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CTestUseLaunchers)
+
 The ``CTestUseLaunchers`` module is automatically included by the
 :module:`CTest` module when ``include(CTest)`` is called.  However, it is
 provided as a separate module so that projects can use the

Modules/ExternalData.cmake

@@ -9,7 +9,14 @@ ExternalData
 
    .. contents::
 
-Manage data files stored outside source tree
+This module provides commands to manage data files stored outside source
+tree.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(ExternalData)
 
 Introduction
 ^^^^^^^^^^^^

Modules/ExternalProject.cmake

@@ -11,6 +11,15 @@ ExternalProject
 
    .. contents::
 
+This module provides commands to download and build external projects as
+part of CMake build phase.
+
+Load this module in CMake with:
+
+.. code-block:: cmake
+
+  include(ExternalProject)
+
 External Project Definition
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Modules/FetchContent.cmake

@@ -11,6 +11,15 @@ FetchContent
 
   .. contents::
 
+This module provides commands to populate content at configure time or as
+part of the calling script.
+
+Load this module in CMake with:
+
+.. code-block:: cmake
+
+  include(FetchContent)
+
 .. note:: The :guide:`Using Dependencies Guide` provides a high-level
   introduction to this general topic. It provides a broader overview of
   where the ``FetchContent`` module fits into the bigger picture,

Modules/FindCUDAToolkit.cmake

@@ -7,9 +7,14 @@ FindCUDAToolkit
 
 .. versionadded:: 3.17
 
-This script locates the NVIDIA CUDA toolkit and the associated libraries, but
-does not require the ``CUDA`` language be enabled for a given project. This
-module does not search for the NVIDIA CUDA Samples.
+Finds the NVIDIA CUDA toolkit and the associated libraries, but does not
+require the ``CUDA`` language be enabled for a given project:
+
+.. code-block:: cmake
+
+  find_package(CUDAToolkit [<version>] [QUIET] [REQUIRED] [EXACT] [...])
+
+This module does not search for the NVIDIA CUDA Samples.
 
 .. versionadded:: 3.19
   QNX support.

Modules/FindDCMTK.cmake

@@ -5,7 +5,14 @@
 FindDCMTK
 ---------
 
-Find DICOM ToolKit (DCMTK) libraries and applications
+Finds the DICOM ToolKit (DCMTK) libraries and applications:
+
+.. code-block:: cmake
+
+  find_package(DCMTK [...])
+
+DCMTK is a set of libraries and applications implementing large parts of
+the DICOM Standard (Digital Imaging and Communications in Medicine).
 
 The module defines the following variables::
 

Modules/FindGTK.cmake

@@ -5,10 +5,6 @@
 FindGTK
 -------
 
-Finds GTK, glib and GTKGLArea.
-
-GTK is a multi-platform toolkit for creating graphical user interfaces.
-
 .. note::
 
   This module works only on Unix-like systems and was intended for early GTK
@@ -22,6 +18,14 @@ GTK is a multi-platform toolkit for creating graphical user interfaces.
     pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14)
     target_link_libraries(example PRIVATE PkgConfig::GTK)
 
+Finds GTK, glib and GTKGLArea:
+
+.. code-block:: cmake
+
+  find_package(GTK [...])
+
+GTK is a multi-platform toolkit for creating graphical user interfaces.
+
 Result Variables
 ^^^^^^^^^^^^^^^^
 

Modules/FindGTK2.cmake

@@ -5,14 +5,10 @@
 FindGTK2
 --------
 
-Finds the GTK widget libraries and several of its other optional components.
-
-GTK is a multi-platform toolkit for creating graphical user interfaces.
-
 .. note::
 
-  This module is specifically for GTK version 2.x, which is obsolete and no
-  longer maintained.  Use the latest supported GTK version and
+  This module is intended specifically for GTK version 2.x, which is obsolete
+  and no longer maintained.  Use the latest supported GTK version and
   :module:`FindPkgConfig` module to find GTK in CMake instead of this module.
   For example:
 
@@ -22,6 +18,14 @@ GTK is a multi-platform toolkit for creating graphical user interfaces.
     pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14)
     target_link_libraries(example PRIVATE PkgConfig::GTK)
 
+Finds the GTK widget libraries and several of its other optional components:
+
+.. code-block:: cmake
+
+  find_package(GTK2 [<version>] [COMPONENTS <components>...] [...])
+
+GTK is a multi-platform toolkit for creating graphical user interfaces.
+
 Components
 ^^^^^^^^^^
 

Modules/FindGit.cmake

@@ -5,7 +5,11 @@
 FindGit
 -------
 
-Finds the Git distributed version control system.
+Finds the Git distributed version control system:
+
+.. code-block:: cmake
+
+  find_package(Git [<version>] [...])
 
 Imported Targets
 ^^^^^^^^^^^^^^^^

Modules/FindHSPELL.cmake

@@ -5,7 +5,11 @@
 FindHSPELL
 ----------
 
-Finds Hebrew spell-checker (Hspell) and morphology engine.
+Finds the Hebrew spell-checker and morphology engine (Hspell):
+
+.. code-block:: cmake
+
+  find_package(HSPELL [<version>] [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^

Modules/FindIcotool.cmake

@@ -6,7 +6,11 @@ FindIcotool
 -----------
 
 Finds ``icotool``, command-line program for converting and creating Win32 icon
-and cursor files.
+and cursor files:
+
+.. code-block:: cmake
+
+  find_package(Icotool [<version>] [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^

Modules/FindImageMagick.cmake

@@ -6,7 +6,11 @@ FindImageMagick
 ---------------
 
 Finds ImageMagick, a software suite for displaying, converting, and manipulating
-raster images.
+raster images:
+
+.. code-block:: cmake
+
+  find_package(ImageMagick [<version>] [COMPONENTS <components>...] [...])
 
 .. versionadded:: 3.9
   Support for ImageMagick 7.

Modules/FindMatlab.cmake

@@ -6,7 +6,11 @@ FindMatlab
 ----------
 
 Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab tools,
-libraries and compilers to CMake.
+libraries and compilers to CMake:
+
+.. code-block:: cmake
+
+  find_package(Matlab [<version>] [COMPONENTS <components>...] [...])
 
 This package primary purpose is to find the libraries associated with Matlab
 or the MCR in order to be able to build Matlab extensions (mex files). It

Modules/FindOpenAL.cmake

@@ -5,7 +5,11 @@
 FindOpenAL
 ----------
 
-Finds the Open Audio Library (OpenAL).
+Finds the Open Audio Library (OpenAL):
+
+.. code-block:: cmake
+
+  find_package(OpenAL [<version>] [...])
 
 OpenAL is a cross-platform 3D audio API designed for efficient rendering of
 multichannel three-dimensional positional audio.  It is commonly used in games

Modules/FindOpenCL.cmake

@@ -7,7 +7,11 @@ FindOpenCL
 
 .. versionadded:: 3.1
 
-Finds Open Computing Language (OpenCL).
+Finds Open Computing Language (OpenCL):
+
+.. code-block:: cmake
+
+  find_package(OpenCL [<version>] [...])
 
 .. versionadded:: 3.10
   Detection of OpenCL 2.1 and 2.2.

Modules/FindPackageHandleStandardArgs.cmake

@@ -5,7 +5,7 @@
 FindPackageHandleStandardArgs
 -----------------------------
 
-This module provides commands intended to be used in :ref:`Find Modules`
+This module provides commands intended for use in :ref:`Find Modules`
 implementing :command:`find_package(<PackageName>)` calls.
 
 Load this module in a CMake find module with:

Modules/FindPackageMessage.cmake

@@ -6,11 +6,13 @@ FindPackageMessage
 ------------------
 
 This module provides a command for printing find result messages and is
-intended for use in :ref:`Find Modules`.
+intended for use in :ref:`Find Modules` implementing
+:command:`find_package(<PackageName>)` calls.
 
-Load it in a CMake find module with:
+Load this module in a CMake find module with:
 
 .. code-block:: cmake
+  :caption: ``FindFoo.cmake``
 
   include(FindPackageMessage)
 

Modules/FindPatch.cmake

@@ -8,7 +8,11 @@ FindPatch
 .. versionadded:: 3.10
 
 Finds the ``patch`` command-line executable for applying diff patches to
-original files.
+original files:
+
+.. code-block:: cmake
+
+  find_package(Patch [...])
 
 Imported Targets
 ^^^^^^^^^^^^^^^^

Modules/FindPike.cmake

@@ -5,8 +5,14 @@
 FindPike
 --------
 
-Finds the Pike compiler and interpreter.  Pike is interpreted, general purpose,
-high-level, dynamic programming language.
+Finds the Pike compiler and interpreter:
+
+.. code-block:: cmake
+
+  find_package(Pike [...])
+
+Pike is interpreted, general purpose, high-level, dynamic programming
+language.
 
 Cache Variables
 ^^^^^^^^^^^^^^^

Modules/FindProducer.cmake

@@ -14,8 +14,8 @@ FindProducer
   library became obsolete and is no longer maintained.  For details about
   OpenSceneGraph usage, refer to the :module:`FindOpenSceneGraph` module.
 
-This module finds the Producer library, a windowing and event handling library
-designed primarily for real-time graphics applications:
+Finds the Producer library, a windowing and event handling library designed
+primarily for real-time graphics applications:
 
 .. code-block:: cmake
 

Modules/FindPython.cmake

@@ -7,8 +7,12 @@ FindPython
 
 .. versionadded:: 3.12
 
-Find Python interpreter, compiler and development environment (include
-directories and libraries).
+Finds Python interpreter, compiler and development environment (include
+directories and libraries):
+
+.. code-block:: cmake
+
+  find_package(Python [<version>] [COMPONENTS <components>...] [...])
 
 .. versionadded:: 3.19
   When a version is requested, it can be specified as a simple value or as a

Modules/FindPython2.cmake

@@ -7,8 +7,12 @@ FindPython2
 
 .. versionadded:: 3.12
 
-Find Python 2 interpreter, compiler and development environment (include
-directories and libraries).
+Finds Python 2 interpreter, compiler and development environment (include
+directories and libraries):
+
+.. code-block:: cmake
+
+  find_package(Python2 [<version>] [COMPONENTS <components>...] [...])
 
 .. versionadded:: 3.19
   When a version is requested, it can be specified as a simple value or as a

Modules/FindPython3.cmake

@@ -7,8 +7,12 @@ FindPython3
 
 .. versionadded:: 3.12
 
-Find Python 3 interpreter, compiler and development environment (include
-directories and libraries).
+Finds Python 3 interpreter, compiler and development environment (include
+directories and libraries):
+
+.. code-block:: cmake
+
+  find_package(Python3 [<version>] [COMPONENTS <components>...] [...])
 
 .. versionadded:: 3.19
   When a version is requested, it can be specified as a simple value or as a

Modules/FindPythonInterp.cmake

@@ -13,8 +13,11 @@ FindPythonInterp
   Use :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython`
   instead.
 
-This module finds the Python interpreter and determines the location of its
-executable.
+Finds the Python interpreter and determines the location of its executable:
+
+.. code-block:: cmake
+
+  find_package(PythonInterp [<version>] [...])
 
 .. note::
 

Modules/FindPythonLibs.cmake

@@ -13,9 +13,13 @@ FindPythonLibs
   Use :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython`
   instead.
 
-This module finds the Python installation and determines the location of its
-include directories and libraries, as well as the name of the Python library to
-link against.
+Finds the Python installation and determines the location of its include
+directories and libraries, as well as the name of the Python library to
+link against:
+
+.. code-block:: cmake
+
+  find_package(PythonLibs [<version>] [...])
 
 .. note::
 

Modules/FindQt.cmake

@@ -11,9 +11,14 @@ FindQt
   ``NEW``.  It supports only Qt3 and Qt4.  For Qt5 or later versions see
   :manual:`cmake-qt(7)`.
 
-This module finds an installed version of Qt3 or Qt4.  Qt is a cross-platform
-application development framework for creating graphical user interfaces and
-applications.
+Finds an installed version of Qt3 or Qt4:
+
+.. code-block:: cmake
+
+  find_package(Qt [...])
+
+Qt is a cross-platform application development framework for creating
+graphical user interfaces and applications.
 
 Use this module only if the project can work with both Qt3 and Qt4
 versions.  If a specific version is required, use :module:`FindQt4` or

Modules/FindUnixCommands.cmake

@@ -9,7 +9,11 @@ FindUnixCommands
 
   Use :option:`${CMAKE_COMMAND} -E <cmake -E>` subcommands instead.
 
-Find Unix commands, including the ones from Cygwin
+Finds Unix commands, including the ones from Cygwin:
+
+.. code-block:: cmake
+
+  find_package(UnixCommands [...])
 
 This module looks for the Unix commands ``bash``, ``cp``, ``gzip``,
 ``mv``, ``rm``, and ``tar`` and stores the result in the variables

Modules/FindX11.cmake

@@ -5,9 +5,13 @@
 FindX11
 -------
 
-Find X11 installation
+Finds the X11 installation on Unix-like systems:
 
-Try to find X11 on UNIX systems. The following values are defined
+.. code-block:: cmake
+
+  find_package(X11 [COMPONENTS <components>...] [...])
+
+The following values are defined
 
 ::
 

Modules/GenerateExportHeader.cmake

@@ -8,7 +8,7 @@ GenerateExportHeader
 This module provides commands for generating a header file containing
 preprocessor macro definitions to control C/C++ symbol visibility.
 
-Load this module in CMake project with:
+Load this module in a CMake project with:
 
 .. code-block:: cmake
 

Modules/GoogleTest.cmake

@@ -7,9 +7,16 @@ GoogleTest
 
 .. versionadded:: 3.9
 
-This module defines functions to help use the Google Test infrastructure.  Two
-mechanisms for adding tests are provided. :command:`gtest_add_tests` has been
-around for some time, originally via ``find_package(GTest)``.
+This module provides commands to help use the Google Test infrastructure.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(GoogleTest)
+
+Two mechanisms for adding tests are provided. :command:`gtest_add_tests` has
+been around for some time, originally via ``find_package(GTest)``.
 :command:`gtest_discover_tests` was introduced in CMake 3.10.
 
 The (older) :command:`gtest_add_tests` scans source files to identify tests.

Modules/InstallRequiredSystemLibraries.cmake

@@ -5,9 +5,17 @@
 InstallRequiredSystemLibraries
 ------------------------------
 
-Include this module to search for compiler-provided system runtime
-libraries and add install rules for them.  Some optional variables
-may be set prior to including the module to adjust behavior:
+This module searches for compiler-provided system runtime libraries and adds
+installation rules for them.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(InstallRequiredSystemLibraries)
+
+Some optional variables may be set prior to including this module to adjust
+behavior:
 
 ``CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS``
   Specify additional runtime libraries that may not be detected.

Modules/SelectLibraryConfigurations.cmake

@@ -5,13 +5,15 @@
 SelectLibraryConfigurations
 ---------------------------
 
-This module is intended for use in :ref:`Find Modules` and provides a
-command to automatically set library variables when package is available
-with multiple :ref:`Build Configurations`.
+This module provides a command to automatically set library variables when
+package is available with multiple :ref:`Build Configurations`.  It is
+intended for use in :ref:`Find Modules` implementing
+:command:`find_package(<PackageName>)` calls.
 
-Load it in a CMake find module with:
+Load this module in a CMake find module with:
 
 .. code-block:: cmake
+  :caption: ``FindFoo.cmake``
 
   include(SelectLibraryConfigurations)
 

Modules/UseEcos.cmake

@@ -8,7 +8,7 @@ UseEcos
 This module defines variables and provides commands required to build an eCos
 application.
 
-Load this module in CMake project with:
+Load this module in a CMake project with:
 
 .. code-block:: cmake
 

Modules/UseJava.cmake

@@ -9,6 +9,12 @@ This file provides support for ``Java``.  It is assumed that
 :module:`FindJava` has already been loaded.  See :module:`FindJava` for
 information on how to load Java into your CMake project.
 
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(UseJava)
+
 Synopsis
 ^^^^^^^^
 

Modules/UseSWIG.cmake

@@ -5,13 +5,19 @@
 UseSWIG
 -------
 
-This file provides support for ``SWIG``. It is assumed that :module:`FindSWIG`
-module has already been loaded.
-
 .. only:: html
 
   .. contents::
 
+This module provides support for ``SWIG``. It is assumed that :module:`FindSWIG`
+module has already been loaded.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(UseSWIG)
+
 CMake Commands
 ^^^^^^^^^^^^^^
 

Modules/WriteCompilerDetectionHeader.cmake

@@ -11,7 +11,20 @@ WriteCompilerDetectionHeader
 
 .. versionadded:: 3.1
 
-This module provides the function ``write_compiler_detection_header()``.
+This module provides a command to generate header with preprocessor macros.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(WriteCompilerDetectionHeader)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
+
+.. command:: write_compiler_detection_header
 
 This function can be used to generate a file suitable for preprocessor
 inclusion which contains macros to be used in source code: