CheckFunctionExists, CheckFortranFunctionExists: Update documentation

Changes:
- Added intro code blocks showing how to include these modules.
- Used "command" instead of "macro".
- Added some basic examples sections.
- Added a rubric title for variables that affect the checks.
- Synced and reworded descriptions.
- Added "See Also" sections.

Modules/CheckFortranFunctionExists.cmake

@@ -5,28 +5,43 @@
 CheckFortranFunctionExists
 --------------------------
 
-Check if a Fortran function exists.
+This module provides a command to check whether a Fortran function exists.
 
-.. command:: check_fortran_function_exists
+Load this module in a CMake project with:
 
 .. code-block:: cmake
 
-    check_fortran_function_exists(<function> <result>)
+  include(CheckFortranFunctionExists)
 
-  where
+Commands
+^^^^^^^^
+
+This module provides the following command:
+
+.. command:: check_fortran_function_exists
+
+  Checks once whether a Fortran function exists:
+
+  .. code-block:: cmake
+
+    check_fortran_function_exists(<function> <variable>)
 
   ``<function>``
-    the name of the Fortran function
+    The name of the Fortran function.
-  ``<result>``
+
-    variable to store the result; will be created as an internal cache variable.
+  ``<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 does not detect functions in Fortran modules. In general it is
+    This command does not detect functions provided by Fortran modules.  In
-  recommended to use :module:`CheckSourceCompiles` instead to determine if a
+    general, it is recommended to use :module:`CheckSourceCompiles` instead
-  Fortran function or subroutine is available.
+    to determine whether a Fortran function or subroutine is available.
 
-The following variables may be set before calling this macro to modify
+  .. 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_LINK_OPTIONS.rst
@@ -34,6 +49,42 @@ the way the check is run:
   .. include:: /module/include/CMAKE_REQUIRED_LIBRARIES.rst
 
   .. include:: /module/include/CMAKE_REQUIRED_LINK_DIRECTORIES.rst
+
+Examples
+^^^^^^^^
+
+Example: Isolated Check With Linked Libraries
+"""""""""""""""""""""""""""""""""""""""""""""
+
+In the following example, this module is used in combination with the
+:module:`CMakePushCheckState` module to temporarily modify the required
+linked libraries (via ``CMAKE_REQUIRED_LIBRARIES``) and verify whether the
+Fortran function ``dgesv`` is available for linking.  The result is stored
+in the internal cache variable ``PROJECT_HAVE_DGESV``:
+
+.. code-block:: cmake
+
+  include(CheckFortranFunctionExists)
+  include(CMakePushCheckState)
+
+  find_package(LAPACK)
+
+  if(TARGET LAPACK::LAPACK)
+    cmake_push_check_state(RESET)
+
+    set(CMAKE_REQUIRED_LIBRARIES LAPACK::LAPACK)
+    check_fortran_function_exists(dgesv PROJECT_HAVE_DGESV)
+
+    cmake_pop_check_state()
+  endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckFunctionExists` module to check whether a C function
+  exists.
+* The :module:`CheckSourceCompiles` module to check whether source code
+  can be compiled.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckFunctionExists.cmake

@@ -5,19 +5,49 @@
 CheckFunctionExists
 -------------------
 
-Check once if a C function can be linked from system libraries.
+This module provides a command to check whether a C function exists.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckFunctionExists)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_function_exists
 
+  Checks once whether a C function can be linked from system libraries:
+
   .. code-block:: cmake
 
     check_function_exists(<function> <variable>)
 
-  Checks that the ``<function>`` is provided by libraries on the system and store
+  This command checks whether the ``<function>`` is provided by libraries
-  the result in internal cache variable ``<variable>``.
+  on the system, and stores the result in an internal cache variable
+  ``<variable>``.
 
-The following variables may be set before calling this macro to modify the
+  .. note::
-way the check is run:
+
+    Prefer using :module:`CheckSymbolExists` or :module:`CheckSourceCompiles`
+    instead of this command, for the following reasons:
+
+    * ``check_function_exists()`` can't detect functions that are inlined
+      in headers or defined as preprocessor macros.
+
+    * ``check_function_exists()`` can't detect anything in the 32-bit
+      versions of the Win32 API, because of a mismatch in calling conventions.
+
+    * ``check_function_exists()`` only verifies linking, it does not verify
+      that the function is declared in system headers.
+
+  .. 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
 
@@ -33,19 +63,63 @@ way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
-.. note::
+Examples
+^^^^^^^^
 
-  Prefer using :module:`CheckSymbolExists` or :module:`CheckSourceCompiles`
+Example: Basic Usage
-  instead of this module, for the following reasons:
+""""""""""""""""""""
 
-  * ``check_function_exists()`` can't detect functions that are inlined
+In the following example, a check is performed to determine whether the
-    in headers or specified as a macro.
+linker sees the C function ``fopen()``, and the result is stored in the
+``HAVE_FOPEN`` internal cache variable:
 
-  * ``check_function_exists()`` can't detect anything in the 32-bit
+.. code-block:: cmake
-    versions of the Win32 API, because of a mismatch in calling conventions.
 
-  * ``check_function_exists()`` only verifies linking, it does not verify
+  include(CheckFunctionExists)
-    that the function is declared in system headers.
+
+  check_function_exists(fopen HAVE_FOPEN)
+
+Example: Missing Declaration
+""""""""""""""""""""""""""""
+
+As noted above, the :module:`CheckSymbolExists` module is preferred for
+checking C functions, since it also verifies whether the function is
+declared or defined as a macro.  In the following example, this module is
+used to check an edge case where a function may not be declared in system
+headers.  For instance, on macOS, the ``fdatasync()`` function may be
+available in the C library, but its declaration is not provided in the
+``unistd.h`` system header.
+
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt``
+
+  include(CheckFunctionExists)
+  include(CheckSymbolExists)
+
+  check_symbol_exists(fdatasync "unistd.h" HAVE_FDATASYNC)
+
+  # Check if fdatasync() is available in the C library.
+  if(NOT HAVE_FDATASYNC)
+    check_function_exists(fdatasync HAVE_FDATASYNC_WITHOUT_DECL)
+  endif()
+
+In such a case, the project can provide its own declaration if missing:
+
+.. code-block:: c
+  :caption: ``example.c``
+
+  #ifdef HAVE_FDATASYNC_WITHOUT_DECL
+    extern int fdatasync(int);
+  #endif
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSymbolExists` module to check whether a C symbol exists.
+* The :module:`CheckSourceCompiles` module to check whether a source code
+  can be compiled.
+* The :module:`CheckFortranFunctionExists` module to check whether a
+  Fortran function exists.
 #]=======================================================================]
 
 include_guard(GLOBAL)