CheckLibraryExists: Update documentation

- Added intro code block showing how to include this module.
- Used "command" instead of "macro".
- Added rubric title for variables that affect the check command.
- Refactored note about using CheckSymbolExists as a more robust check.

Modules/CheckLibraryExists.cmake

@@ -5,25 +5,66 @@
 CheckLibraryExists
 ------------------
 
-Check once if the function exists in system or specified library.
+This module provides a command to check whether a C library exists.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckLibraryExists)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_library_exists
 
+  Checks once whether a specified library exists and a given C function is
+  available:
+
   .. code-block:: cmake
 
     check_library_exists(<library> <function> <location> <variable>)
 
-  Check that the library ``<library>`` exists in the given location
+  This command attempts to link a test executable that uses the specified
-  ``<location>`` and has the specified ``<function>``. The result is stored in
+  C ``<function>`` to verify that it is provided by either a system or
-  an internal cache variable ``<variable>``. If ``<location>`` is empty string,
+  user-provided ``<library>``.
-  default directories are searched.
 
-Prefer using :module:`CheckSymbolExists` or :module:`CheckSourceCompiles`
+  The arguments are:
-instead of this module for more robust detection if a function is available in
-a library.
 
-The following variables may be set before calling this macro to modify
+  ``<library>``
-the way the check is run:
+    The name of the library, a full path to a library file, or an
+    :ref:`Imported Target <Imported Targets>`.
+
+  ``<function>``
+    The name of a function that should be available in the system or
+    user-provided library ``<library>``.
+
+  ``<location>``
+    The directory containing the library file.  It is added to the link
+    search path during the check.  If this is an empty string, only the
+    default library search paths are used.
+
+  ``<variable>``
+    The name of the variable in which to store the check result.  This
+    variable will be created as an internal cache variable.
+
+  .. note::
+
+    This command is intended for performing basic sanity checks to verify
+    that a library provides the expected functionality, or that the correct
+    library is being located.  However, it only verifies that a function
+    symbol can be linked successfully - it does not ensure that the function
+    is declared in library headers, nor can it detect functions that are
+    inlined or defined as preprocessor macros.  For more robust detection
+    of function availability, prefer using :module:`CheckSymbolExists` or
+    :module:`CheckSourceCompiles`.
+
+  .. rubric:: Variables Affecting the Check
+
+  The following variables may be set before calling this command to modify
+  the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst
 
@@ -40,12 +81,8 @@ the way the check is run:
 Examples
 ^^^^^^^^
 
-This module can be useful for performing so-called sanity checks to verify that
+Checking if the ``curl`` library exists in the default paths and has the
-the specified library provides the expected functionality and is indeed the
+``curl_easy_perform()`` function:
-correct one being located.
-
-For example, to check if the ``curl`` library exists in the default paths and
-has the ``curl_easy_perform`` function:
 
 .. code-block:: cmake
 
@@ -60,8 +97,8 @@ function:
   include(CheckLibraryExists)
   check_library_exists(curl curl_easy_perform "/opt/curl/lib" HAVE_LIBRARY_CURL)
 
-Also :ref:`IMPORTED library <add_library imported libraries>` (for example,
+Also :ref:`Imported Targets` (for example, from the ``find_package()`` call)
-from the ``find_package()`` call) can be used:
+can be used:
 
 .. code-block:: cmake
 
@@ -73,6 +110,11 @@ from the ``find_package()`` call) can be used:
     include(CheckLibraryExists)
     check_library_exists(CURL::libcurl curl_easy_perform "" HAVE_LIBRARY_CURL)
   endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSymbolExists` module to check whether a C symbol exists.
 #]=======================================================================]
 
 include_guard(GLOBAL)