FindPkgConfig: Cleanup docs

- Moved block of misplaced comments to correct section
- Improved grammar, readability and consistency
- Updated to conform to style guidelines

Modules/FindPkgConfig.cmake

@@ -1,19 +1,22 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.
 
-#.rst:
-# FindPkgConfig
-# -------------
-#
-# A `pkg-config` module for CMake.
-#
-# Finds the ``pkg-config`` executable and add the
-# :command:`pkg_check_modules` and :command:`pkg_search_module`
-# commands.
-#
-# In order to find the ``pkg-config`` executable, it uses the
-# :variable:`PKG_CONFIG_EXECUTABLE` variable or the ``PKG_CONFIG``
-# environment variable first.
+#[========================================[.rst:
+FindPkgConfig
+-------------
+
+A ``pkg-config`` module for CMake.
+
+Finds the ``pkg-config`` executable and adds the :command:`pkg_get_variable`,
+:command:`pkg_check_modules` and :command:`pkg_search_module` commands. The
+following variables will also be set::
+
+  PKG_CONFIG_FOUND          ... if pkg-config executable was found
+  PKG_CONFIG_EXECUTABLE     ... pathname of the pkg-config program
+  PKG_CONFIG_VERSION_STRING ... the version of the pkg-config program found
+                                (since CMake 2.8.8)
+
+#]========================================]
 
 ### Common stuff ####
 set(PKG_CONFIG_VERSION 1)
@@ -82,12 +85,13 @@ endmacro()
 #[========================================[.rst:
 .. command:: pkg_get_variable
 
-  Retrieves the value of a variable from a package::
+  Retrieves the value of a pkg-config variable ``varName`` and stores it in the
+  result variable ``resultVar`` in the calling scope. ::
 
-    pkg_get_variable(<RESULT> <MODULE> <VARIABLE>)
+    pkg_get_variable(<resultVar> <moduleName> <varName>)
 
-  If multiple values are returned variable will contain a
-  :ref:`;-list <CMake Language Lists>`.
+  If ``pkg-config`` returns multiple values for the specified variable,
+  ``resultVar`` will contain a :ref:`;-list <CMake Language Lists>`.
 
   For example:
 
@@ -472,117 +476,106 @@ macro(_pkg_check_modules_internal _is_required _is_silent _no_cmake_path _no_cma
   endif()
 endmacro()
 
-###
-### User visible macros start here
-###
 
 #[========================================[.rst:
 .. command:: pkg_check_modules
 
- Checks for all the given modules. ::
+  Checks for all the given modules, setting a variety of result variables in
+  the calling scope. ::
 
-    pkg_check_modules(<PREFIX> [REQUIRED] [QUIET]
-                      [NO_CMAKE_PATH] [NO_CMAKE_ENVIRONMENT_PATH]
+    pkg_check_modules(<prefix>
+                      [REQUIRED] [QUIET]
+                      [NO_CMAKE_PATH]
+                      [NO_CMAKE_ENVIRONMENT_PATH]
                       [IMPORTED_TARGET]
-                      <MODULE> [<MODULE>]*)
-
-
- When the ``REQUIRED`` argument was set, macros will fail with an error
- when module(s) could not be found.
-
- When the ``QUIET`` argument is set, no status messages will be printed.
-
- By default, if :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` is 3.1 or
- later, or if :variable:`PKG_CONFIG_USE_CMAKE_PREFIX_PATH` is set, the
- :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_FRAMEWORK_PATH`, and
- :variable:`CMAKE_APPBUNDLE_PATH` cache and environment variables will
- be added to ``pkg-config`` search path.
- The ``NO_CMAKE_PATH`` and ``NO_CMAKE_ENVIRONMENT_PATH`` arguments
- disable this behavior for the cache variables and the environment
- variables, respectively.
- The ``IMPORTED_TARGET`` argument will create an imported target named
- PkgConfig::<PREFIX>> that can be passed directly as an argument to
- :command:`target_link_libraries`.
-
- It sets the following variables: ::
-
-    PKG_CONFIG_FOUND          ... if pkg-config executable was found
-    PKG_CONFIG_EXECUTABLE     ... pathname of the pkg-config program
-    PKG_CONFIG_VERSION_STRING ... the version of the pkg-config program found
-                                  (since CMake 2.8.8)
-
- For the following variables two sets of values exist; first one is the
- common one and has the given PREFIX.  The second set contains flags
- which are given out when ``pkg-config`` was called with the ``--static``
- option. ::
-
-    <XPREFIX>_FOUND          ... set to 1 if module(s) exist
-    <XPREFIX>_LIBRARIES      ... only the libraries (w/o the '-l')
-    <XPREFIX>_LIBRARY_DIRS   ... the paths of the libraries (w/o the '-L')
-    <XPREFIX>_LDFLAGS        ... all required linker flags
-    <XPREFIX>_LDFLAGS_OTHER  ... all other linker flags
-    <XPREFIX>_INCLUDE_DIRS   ... the '-I' preprocessor flags (w/o the '-I')
-    <XPREFIX>_CFLAGS         ... all required cflags
-    <XPREFIX>_CFLAGS_OTHER   ... the other compiler flags
+                      <moduleSpec> [<moduleSpec>...])
+
+  When the ``REQUIRED`` argument is given, the command will fail with an error
+  if module(s) could not be found.
+
+  When the ``QUIET`` argument is given, no status messages will be printed.
+
+  By default, if :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` is 3.1 or
+  later, or if :variable:`PKG_CONFIG_USE_CMAKE_PREFIX_PATH` is set to a
+  boolean ``True`` value, then the :variable:`CMAKE_PREFIX_PATH`,
+  :variable:`CMAKE_FRAMEWORK_PATH`, and :variable:`CMAKE_APPBUNDLE_PATH` cache
+  and environment variables will be added to the ``pkg-config`` search path.
+  The ``NO_CMAKE_PATH`` and ``NO_CMAKE_ENVIRONMENT_PATH`` arguments
+  disable this behavior for the cache variables and environment variables
+  respectively.
+
+  The ``IMPORTED_TARGET`` argument will create an imported target named
+  ``PkgConfig::<prefix>`` that can be passed directly as an argument to
+  :command:`target_link_libraries`.
+
+  Each ``<moduleSpec>`` must be in one of the following formats::
+
+    {moduleName}            ... matches any version
+    {moduleName}>={version} ... at least version <version> is required
+    {moduleName}={version}  ... exactly version <version> is required
+    {moduleName}<={version} ... modules must not be newer than <version>
+
+  The following variables may be set upon return.  Two sets of values exist,
+  one for the common case (``<XXX> = <prefix>``) and another for the
+  information ``pkg-config`` provides when it is called with the ``--static``
+  option (``<XXX> = <prefix>_STATIC``)::
+
+    <XXX>_FOUND          ... set to 1 if module(s) exist
+    <XXX>_LIBRARIES      ... only the libraries (without the '-l')
+    <XXX>_LIBRARY_DIRS   ... the paths of the libraries (without the '-L')
+    <XXX>_LDFLAGS        ... all required linker flags
+    <XXX>_LDFLAGS_OTHER  ... all other linker flags
+    <XXX>_INCLUDE_DIRS   ... the '-I' preprocessor flags (without the '-I')
+    <XXX>_CFLAGS         ... all required cflags
+    <XXX>_CFLAGS_OTHER   ... the other compiler flags
+
+  All but ``<XXX>_FOUND`` may be a :ref:`;-list <CMake Language Lists>` if the
+  associated variable returned from ``pkg-config`` has multiple values.
+
+  There are some special variables whose prefix depends on the number of
+  ``<moduleSpec>`` given.  When there is only one ``<moduleSpec>``,
+  ``<YYY>`` will simply be ``<prefix>``, but if two or more ``<moduleSpec>``
+  items are given, ``<YYY>`` will be ``<prefix>_<moduleName>``::
+
+    <YYY>_VERSION    ... version of the module
+    <YYY>_PREFIX     ... prefix directory of the module
+    <YYY>_INCLUDEDIR ... include directory of the module
+    <YYY>_LIBDIR     ... lib directory of the module
+
+  Examples
 
- ::
-
-    <XPREFIX> = <PREFIX>        for common case
-    <XPREFIX> = <PREFIX>_STATIC for static linking
-
- Every variable containing multiple values will be a
- :ref:`;-list <CMake Language Lists>`.
-
- There are some special variables whose prefix depends on the count of
- given modules.  When there is only one module, <PREFIX> stays
- unchanged.  When there are multiple modules, the prefix will be
- changed to <PREFIX>_<MODNAME>: ::
-
-    <XPREFIX>_VERSION    ... version of the module
-    <XPREFIX>_PREFIX     ... prefix-directory of the module
-    <XPREFIX>_INCLUDEDIR ... include-dir of the module
-    <XPREFIX>_LIBDIR     ... lib-dir of the module
-
- ::
-
-    <XPREFIX> = <PREFIX>  when |MODULES| == 1, else
-    <XPREFIX> = <PREFIX>_<MODNAME>
-
- A <MODULE> parameter can have the following formats: ::
-
-    {MODNAME}            ... matches any version
-    {MODNAME}>={VERSION} ... at least version <VERSION> is required
-    {MODNAME}={VERSION}  ... exactly version <VERSION> is required
-    {MODNAME}<={VERSION} ... modules must not be newer than <VERSION>
-
- Examples
+  .. code-block:: cmake
 
- .. code-block:: cmake
+    pkg_check_modules (GLIB2 glib-2.0)
 
-    pkg_check_modules (GLIB2   glib-2.0)
+  Looks for any version of glib2.  If found, the output variable
+  ``GLIB2_VERSION`` will hold the actual version found.
 
- .. code-block:: cmake
+  .. code-block:: cmake
 
-    pkg_check_modules (GLIB2   glib-2.0>=2.10)
+    pkg_check_modules (GLIB2 glib-2.0>=2.10)
 
- Requires at least version 2.10 of glib2 and defines e.g.
- ``GLIB2_VERSION=2.10.3``
+  Looks for at least version 2.10 of glib2.  If found, the output variable
+  ``GLIB2_VERSION`` will hold the actual version found.
 
- .. code-block:: cmake
+  .. code-block:: cmake
 
-    pkg_check_modules (FOO     glib-2.0>=2.10 gtk+-2.0)
+    pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
 
- Requires both glib2 and gtk2, and defines e.g.
- ``FOO_glib-2.0_VERSION=2.10.3`` and ``FOO_gtk+-2.0_VERSION=2.8.20``
+  Looks for both glib2-2.0 (at least version 2.10) and any version of
+  gtk2+-2.0.  Only if both are found will ``FOO`` be considered found.
+  The ``FOO_glib-2.0_VERSION`` and ``FOO_gtk+-2.0_VERSION`` variables will be
+  set to their respective found module versions.
 
- .. code-block:: cmake
+  .. code-block:: cmake
 
     pkg_check_modules (XRENDER REQUIRED xrender)
 
- Defines for example::
+  Requires any version of ``xrender``.  Example output variables set by a
+  successful call::
 
-   XRENDER_LIBRARIES=Xrender;X11``
-   XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
+    XRENDER_LIBRARIES=Xrender;X11
+    XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
 #]========================================]
 macro(pkg_check_modules _prefix _module0)
   _pkgconfig_parse_options(_pkg_modules _pkg_is_required _pkg_is_silent _no_cmake_path _no_cmake_environment_path _imp_target "${_module0}" ${ARGN})
@@ -605,19 +598,22 @@ endmacro()
 #[========================================[.rst:
 .. command:: pkg_search_module
 
- Same as :command:`pkg_check_modules`, but instead it checks for given
- modules and uses the first working one. ::
+  The behavior of this command is the same as :command:`pkg_check_modules`,
+  except that rather than checking for all the specified modules, it searches
+  for just the first successful match. ::
 
-    pkg_search_module(<PREFIX> [REQUIRED] [QUIET]
-                      [NO_CMAKE_PATH] [NO_CMAKE_ENVIRONMENT_PATH]
+    pkg_search_module(<prefix>
+                      [REQUIRED] [QUIET]
+                      [NO_CMAKE_PATH]
+                      [NO_CMAKE_ENVIRONMENT_PATH]
                       [IMPORTED_TARGET]
-                      <MODULE> [<MODULE>]*)
+                      <moduleSpec> [<moduleSpec>...])
 
- Examples
+  Examples
 
- .. code-block:: cmake
+  .. code-block:: cmake
 
-    pkg_search_module (BAR     libxml-2.0 libxml2 libxml>=2)
+    pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
 #]========================================]
 macro(pkg_search_module _prefix _module0)
   _pkgconfig_parse_options(_pkg_modules_alt _pkg_is_required _pkg_is_silent _no_cmake_path _no_cmake_environment_path _imp_target "${_module0}" ${ARGN})
@@ -654,21 +650,26 @@ endmacro()
 
 
 #[========================================[.rst:
-.. variable:: PKG_CONFIG_EXECUTABLE
+Variables Affecting Behavior
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
- Path to the pkg-config executable.
+.. variable:: PKG_CONFIG_EXECUTABLE
 
+  This can be set to the path of the pkg-config executable.  If not provided,
+  it will be set by the module as a result of calling :command:`find_program`
+  internally.  The ``PKG_CONFIG`` environment variable can be used as a hint.
 
 .. variable:: PKG_CONFIG_USE_CMAKE_PREFIX_PATH
 
- Whether :command:`pkg_check_modules` and :command:`pkg_search_module`
- should add the paths in :variable:`CMAKE_PREFIX_PATH`,
- :variable:`CMAKE_FRAMEWORK_PATH`, and :variable:`CMAKE_APPBUNDLE_PATH`
- cache and environment variables to ``pkg-config`` search path.
+  Specifies whether :command:`pkg_check_modules` and
+  :command:`pkg_search_module` should add the paths in the
+  :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_FRAMEWORK_PATH` and
+  :variable:`CMAKE_APPBUNDLE_PATH` cache and environment variables to the
+  ``pkg-config`` search path.
 
- If this variable is not set, this behavior is enabled by default if
- :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` is 3.1 or later, disabled
- otherwise.
+  If this variable is not set, this behavior is enabled by default if
+  :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` is 3.1 or later, disabled
+  otherwise.
 #]========================================]