Help: Revise CheckIncludeFile* documentation

Improve formatting.  Link from each module to the other two.  Explain
the command signatures in more detail.

3 files changed, 56 insertions, 48 deletions

diff --git a/Modules/CheckIncludeFile.cmake b/Modules/CheckIncludeFile.cmake
index 402b37c..ef1e39d 100644
--- a/Modules/CheckIncludeFile.cmake
+++ b/Modules/CheckIncludeFile.cmake
@@ -2,30 +2,34 @@
 # CheckIncludeFile
 # ----------------
 #
-# macro which checks the include file exists.
+# Provides a macro to check if a header file can be included in ``C``.
 #
-# CHECK_INCLUDE_FILE(INCLUDE VARIABLE)
+# .. command:: CHECK_INCLUDE_FILE
 #
-# ::
+#   ::
 #
-#   INCLUDE  - name of include file
-#   VARIABLE - variable to return result
-#              Will be created as an internal cache variable.
+#     CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
 #
-#
-#
-# an optional third argument is the CFlags to add to the compile line or
-# you can use CMAKE_REQUIRED_FLAGS
+#   Check if the given ``<include>`` file may be included in a ``C``
+#   source file and store the result in an internal cache entry named
+#   ``<variable>``.  The optional third argument may be used to add
+#   compilation flags to the check (or use ``CMAKE_REQUIRED_FLAGS`` below).
 #
 # The following variables may be set before calling this macro to modify
 # the way the check is run:
 #
-# ::
+# ``CMAKE_REQUIRED_FLAGS``
+#   string of compile command line flags
+# ``CMAKE_REQUIRED_DEFINITIONS``
+#   list of macros to define (-DFOO=bar)
+# ``CMAKE_REQUIRED_INCLUDES``
+#   list of include directories
+# ``CMAKE_REQUIRED_QUIET``
+#   execute quietly without messages
 #
-#   CMAKE_REQUIRED_FLAGS = string of compile command line flags
-#   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
-#   CMAKE_REQUIRED_INCLUDES = list of include directories
-#   CMAKE_REQUIRED_QUIET = execute quietly without messages
+# See the :module:`CheckIncludeFiles` module to check for multiple headers
+# at once.  See the :module:`CheckIncludeFileCXX` module to check for headers
+# using the ``CXX`` language.
 
 #=============================================================================
 # Copyright 2002-2009 Kitware, Inc.
diff --git a/Modules/CheckIncludeFileCXX.cmake b/Modules/CheckIncludeFileCXX.cmake
index eae1730..9a6df3b 100644
--- a/Modules/CheckIncludeFileCXX.cmake
+++ b/Modules/CheckIncludeFileCXX.cmake
@@ -2,34 +2,33 @@
 # CheckIncludeFileCXX
 # -------------------
 #
-# Check if the include file exists.
+# Provides a macro to check if a header file can be included in ``CXX``.
 #
-# ::
+# .. command:: CHECK_INCLUDE_FILE_CXX
 #
-#   CHECK_INCLUDE_FILE_CXX(INCLUDE VARIABLE)
+#   ::
 #
+#     CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])
 #
-#
-# ::
-#
-#   INCLUDE  - name of include file
-#   VARIABLE - variable to return result
-#              Will be created as an internal cache variable.
-#
-#
-#
-# An optional third argument is the CFlags to add to the compile line or
-# you can use CMAKE_REQUIRED_FLAGS.
+#   Check if the given ``<include>`` file may be included in a ``CXX``
+#   source file and store the result in an internal cache entry named
+#   ``<variable>``.  The optional third argument may be used to add
+#   compilation flags to the check (or use ``CMAKE_REQUIRED_FLAGS`` below).
 #
 # The following variables may be set before calling this macro to modify
 # the way the check is run:
 #
-# ::
+# ``CMAKE_REQUIRED_FLAGS``
+#   string of compile command line flags
+# ``CMAKE_REQUIRED_DEFINITIONS``
+#   list of macros to define (-DFOO=bar)
+# ``CMAKE_REQUIRED_INCLUDES``
+#   list of include directories
+# ``CMAKE_REQUIRED_QUIET``
+#   execute quietly without messages
 #
-#   CMAKE_REQUIRED_FLAGS = string of compile command line flags
-#   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
-#   CMAKE_REQUIRED_INCLUDES = list of include directories
-#   CMAKE_REQUIRED_QUIET = execute quietly without messages
+# See modules :module:`CheckIncludeFile` and :module:`CheckIncludeFiles`
+# to check for one or more ``C`` headers.
 
 #=============================================================================
 # Copyright 2002-2009 Kitware, Inc.
diff --git a/Modules/CheckIncludeFiles.cmake b/Modules/CheckIncludeFiles.cmake
index 2494862..843cd35 100644
--- a/Modules/CheckIncludeFiles.cmake
+++ b/Modules/CheckIncludeFiles.cmake
@@ -2,29 +2,34 @@
 # CheckIncludeFiles
 # -----------------
 #
-# Check if the files can be included
+# Provides a macro to check if a list of one or more header files can
+# be included together in ``C``.
 #
+# .. command:: CHECK_INCLUDE_FILES
 #
+#   ::
 #
-# CHECK_INCLUDE_FILES(INCLUDE VARIABLE)
-#
-# ::
-#
-#   INCLUDE  - list of files to include
-#   VARIABLE - variable to return result
-#              Will be created as an internal cache variable.
-#
+#     CHECK_INCLUDE_FILES("<includes>" <variable>)
 #
+#   Check if the given ``<includes>`` list may be included together
+#   in a ``C`` source file and store the result in an internal cache
+#   entry named ``<variable>``.  Specify the ``<includes>`` argument
+#   as a :ref:`;-list <CMake Language Lists>` of header file names.
 #
 # The following variables may be set before calling this macro to modify
 # the way the check is run:
 #
-# ::
+# ``CMAKE_REQUIRED_FLAGS``
+#   string of compile command line flags
+# ``CMAKE_REQUIRED_DEFINITIONS``
+#   list of macros to define (-DFOO=bar)
+# ``CMAKE_REQUIRED_INCLUDES``
+#   list of include directories
+# ``CMAKE_REQUIRED_QUIET``
+#   execute quietly without messages
 #
-#   CMAKE_REQUIRED_FLAGS = string of compile command line flags
-#   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
-#   CMAKE_REQUIRED_INCLUDES = list of include directories
-#   CMAKE_REQUIRED_QUIET = execute quietly without messages
+# See modules :module:`CheckIncludeFile` and :module:`CheckIncludeFileCXX`
+# to check for a single header file in ``C`` or ``CXX`` languages.
 
 #=============================================================================
 # Copyright 2003-2012 Kitware, Inc.