CheckSymbolExists, CheckCXXSymbolExists: Update documentation

- Added intro code blocks showing how to include these modules.
- Added section titles.
- Used "command" instead of "macro".
- Indented command-related descriptions according to the command
  section indentation level.
- Added the "See Also" sections.
- Synced descriptions between the modules.

Help/manual/cmake-toolchains.7.rst

@@ -83,7 +83,7 @@ with the :prop_tgt:`LINKER_LANGUAGE` target property.
 Toolchain Features
 ==================
 
-CMake provides the :command:`try_compile` command and wrapper macros such as
+CMake provides the :command:`try_compile` command and modules such as
 :module:`CheckSourceCompiles`, :module:`CheckCXXSymbolExists` and
 :module:`CheckIncludeFile` to test capability and availability of various
 toolchain features. These APIs test the toolchain in some way and cache the

Modules/CheckCXXSymbolExists.cmake

@@ -5,41 +5,61 @@
 CheckCXXSymbolExists
 --------------------
 
-Check if a symbol exists as a function, variable, or macro in ``C++``.
+This module provides a command to check whether a C++ symbol exists.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckCXXSymbolExists)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_cxx_symbol_exists
 
+  Checks once whether a symbol exists as a function, variable, or preprocessor
+  macro in C++:
+
   .. code-block:: cmake
 
-    check_cxx_symbol_exists(<symbol> <files> <variable>)
+    check_cxx_symbol_exists(<symbol> <headers> <variable>)
 
-  Check that the ``<symbol>`` is available after including given header
-  ``<files>`` and store the result in a ``<variable>``.  Specify the list of
-  files in one argument as a semicolon-separated list.
-  ``check_cxx_symbol_exists()`` can be used to check for symbols as seen by
-  the C++ compiler, as opposed to :command:`check_symbol_exists`, which always
-  uses the ``C`` compiler.
+  This command checks whether the ``<symbol>`` is available after including
+  the specified header file(s) ``<headers>``, and stores the result in the
+  internal cache variable ``<variable>``.  Multiple header files can be
+  specified in one argument as a string using a
+  :ref:`semicolon-separated list <CMake Language Lists>`.
 
-  If the header files define the symbol as a macro it is considered
-  available and assumed to work.  If the header files declare the symbol
-  as a function or variable then the symbol must also be available for
-  linking.  If the symbol is a type, enum value, or C++ template it will
-  not be recognized: consider using the :module:`CheckTypeSize`
-  or :module:`CheckSourceCompiles` module instead.
+  If the header files define the symbol as a macro, it is considered
+  available and assumed to work.  If the symbol is declared as a function
+  or variable, the check also ensures that it links successfully
+  (i.e., the symbol must exist in a linked library or object file).
 
-.. note::
+  Symbols that are types, enum values, or C++ templates are not
+  recognized.  For those, consider using the :module:`CheckTypeSize` or
+  :module:`CheckSourceCompiles` module instead.
 
-  This command is unreliable when ``<symbol>`` is (potentially) an overloaded
-  function. Since there is no reliable way to predict whether a given function
-  in the system environment may be defined as an overloaded function or may be
-  an overloaded function on other systems or will become so in the future, it
-  is generally advised to use the :module:`CheckSourceCompiles` module for
-  checking any function symbol (unless somehow you surely know the checked
-  function is not overloaded on other systems or will not be so in the
-  future).
+  This command is intended to check symbols as they appear in C++.  For C
+  symbols, use the :module:`CheckSymbolExists` module instead.
 
-The following variables may be set before calling this macro to modify
-the way the check is run:
+  .. note::
+
+    This command is unreliable for symbols that are (potentially) overloaded
+    functions.  Since there is no reliable way to predict whether
+    a given function in the system environment may be defined as an
+    overloaded function or may be an overloaded function on other systems
+    or will become so in the future, it is generally advised to use the
+    :module:`CheckSourceCompiles` module for checking any function symbol
+    (unless it is certain the checked function is not overloaded on other
+    systems or will not be so in the future).
+
+  .. 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
 
@@ -55,7 +75,12 @@ the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
-For example:
+Examples
+^^^^^^^^
+
+The following example demonstrates how to check for the presence of a
+preprocessor macro ``SEEK_SET`` and the C++ function ``std::fopen()`` from
+the ``<cstdio>`` header using this module:
 
 .. code-block:: cmake
 
@@ -63,8 +88,14 @@ For example:
 
   # Check for macro SEEK_SET
   check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET)
+
   # Check for function std::fopen
   check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSymbolExists` module to check whether a C symbol exists.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckSymbolExists.cmake

@@ -5,31 +5,52 @@
 CheckSymbolExists
 -----------------
 
-Provides a macro to check if a symbol exists as a function, variable,
-or macro in ``C``.
+This module provides a command to check whether a C symbol exists.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckSymbolExists)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_symbol_exists
 
+  Checks once whether a symbol exists as a function, variable, or preprocessor
+  macro in C:
+
   .. code-block:: cmake
 
-    check_symbol_exists(<symbol> <files> <variable>)
+    check_symbol_exists(<symbol> <headers> <variable>)
 
-  Check that the ``<symbol>`` is available after including given header
-  ``<files>`` and store the result in a ``<variable>``.  Specify the list
-  of files in one argument as a semicolon-separated list.
-  ``<variable>`` will be created as an internal cache variable.
+  This command checks whether the ``<symbol>`` is available after including
+  the specified header file(s) ``<headers>``, and stores the result in the
+  internal cache variable ``<variable>``.  Multiple header files can be
+  specified in one argument as a string using a
+  :ref:`semicolon-separated list <CMake Language Lists>`.
 
-If the header files define the symbol as a macro it is considered
-available and assumed to work.  If the header files declare the symbol
-as a function or variable then the symbol must also be available for
-linking (so intrinsics may not be detected).
-If the symbol is a type, enum value, or intrinsic it will not be recognized
-(consider using :module:`CheckTypeSize` or :module:`CheckSourceCompiles`).
-If the check needs to be done in C++, consider using
-:module:`CheckCXXSymbolExists` instead.
+  If the header files define the symbol as a macro, it is considered
+  available and assumed to work.  If the symbol is declared as a function
+  or variable, the check also ensures that it links successfully
+  (i.e., the symbol must exist in a linked library or object file).
+  Compiler intrinsics may not be detected, as they are not always linkable
+  or explicitly declared in headers.
 
-The following variables may be set before calling this macro to modify
-the way the check is run:
+  Symbols that are types, enum values, or compiler intrinsics are not
+  recognized.  For those, consider using the :module:`CheckTypeSize` or
+  :module:`CheckSourceCompiles` module instead.
+
+  This command is intended to check symbols as they appear in C.  For C++
+  symbols, use the :module:`CheckCXXSymbolExists` module instead.
+
+  .. 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
 
@@ -45,7 +66,12 @@ the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
-For example:
+Examples
+^^^^^^^^
+
+The following example demonstrates how to check for the presence of a
+preprocessor macro ``SEEK_SET`` and the C function ``fopen()`` from
+the ``<stdio.h>`` header using this module:
 
 .. code-block:: cmake
 
@@ -53,8 +79,15 @@ For example:
 
   # Check for macro SEEK_SET
   check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
+
   # Check for function fopen
   check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckCXXSymbolExists` module to check whether a C++ symbol
+  exists.
 #]=======================================================================]
 
 include_guard(GLOBAL)