Help: Revise CheckIncludeFile* documentation

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

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
+#     CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
-#   VARIABLE - variable to return result
-#              Will be created as an internal cache variable.
 #
-#
+#   Check if the given ``<include>`` file may be included in a ``C``
-#
+#   source file and store the result in an internal cache entry named
-# an optional third argument is the CFlags to add to the compile line or
+#   ``<variable>``.  The optional third argument may be used to add
-# you can use CMAKE_REQUIRED_FLAGS
+#   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
+# See the :module:`CheckIncludeFiles` module to check for multiple headers
-#   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
+# at once.  See the :module:`CheckIncludeFileCXX` module to check for headers
-#   CMAKE_REQUIRED_INCLUDES = list of include directories
+# using the ``CXX`` language.
-#   CMAKE_REQUIRED_QUIET = execute quietly without messages
 
 #=============================================================================
 # Copyright 2002-2009 Kitware, Inc.

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>])
 #
-#
+#   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).
-#   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.
 #
 # 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
+# See modules :module:`CheckIncludeFile` and :module:`CheckIncludeFiles`
-#   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
+# to check for one or more ``C`` headers.
-#   CMAKE_REQUIRED_INCLUDES = list of include directories
-#   CMAKE_REQUIRED_QUIET = execute quietly without messages
 
 #=============================================================================
 # Copyright 2002-2009 Kitware, Inc.

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
+#     CHECK_INCLUDE_FILES("<includes>" <variable>)
-#   VARIABLE - variable to return result
-#              Will be created as an internal cache 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
+# See modules :module:`CheckIncludeFile` and :module:`CheckIncludeFileCXX`
-#   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
+# to check for a single header file in ``C`` or ``CXX`` languages.
-#   CMAKE_REQUIRED_INCLUDES = list of include directories
-#   CMAKE_REQUIRED_QUIET = execute quietly without messages
 
 #=============================================================================
 # Copyright 2003-2012 Kitware, Inc.