Help: Revise CheckIncludeFile* documentation

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

1 files changed, 19 insertions, 15 deletions

diff --git a/Modules/CheckIncludeFile.cmake b/Modules/CheckIncludeFile.cmake
index 402b37c6aa..ef1e39d69e 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.