Cleanup generic compiler check macro documentation

This commit improves formatting and style of the documentation for the
general-purpose compiler check macros:

  CHECK_C_COMPILER_FLAG
  CHECK_C_SOURCE_COMPILES
  CHECK_C_SOURCE_RUNS
  CHECK_CXX_COMPILER_FLAG
  CHECK_CXX_SOURCE_COMPILES
  CHECK_CXX_SOURCE_RUNS

This sytle is more consistent with CMake command documentation.
It also looks nicer in the generated documentation text files.

Modules/CheckCCompilerFlag.cmake

@@ -1,10 +1,8 @@
 # - Check whether the C compiler supports a given flag.
-# CHECK_C_COMPILER_FLAG(FLAG VARIABLE)
+# CHECK_C_COMPILER_FLAG(<flag> <var>)
-#
+#  <flag> - the compiler flag
-#  FLAG - the compiler flag
+#  <var>  - variable to store the result
-#  VARIABLE - variable to store the result
+# This internally calls the check_c_source_compiles macro.
-# 
-#  This actually calls the check_c_source_compiles macro.
 # See help for CheckCSourceCompiles for a listing of variables
 # that can modify the build.
 

Modules/CheckCSourceCompiles.cmake

@@ -1,9 +1,7 @@
-# - Check if the C source code provided in the SOURCE argument compiles.
+# - Check if the given C source code compiles.
-# CHECK_C_SOURCE_COMPILES(SOURCE VAR)
+# CHECK_C_SOURCE_COMPILES(<code> <var>)
-#
+#  <code>       - source code to try to compile
-#  SOURCE   - source code to try to compile
+#  <var>        - variable to store whether the source code compiled
-#  VAR      - variable to store whether the source code compiled
-#
 # The following variables may be set before calling this macro to
 # modify the way the check is run:
 #

Modules/CheckCSourceRuns.cmake

@@ -1,9 +1,8 @@
-# - Check if the C source code provided in the SOURCE argument compiles and runs.
+# - Check if the given C source code compiles and runs.
-# CHECK_C_SOURCE_RUNS(SOURCE VAR)
+# CHECK_C_SOURCE_RUNS(<code> <var>)
-#
+#  <code>   - source code to try to compile
-#  SOURCE   - source code to try to compile
+#  <var>    - variable to store the result
-#  VAR      - variable to store the result, 1 for success, empty for failure
+#             (1 for success, empty for failure)
-#
 # The following variables may be set before calling this macro to
 # modify the way the check is run:
 #

Modules/CheckCXXCompilerFlag.cmake

@@ -1,8 +1,10 @@
 # - Check whether the CXX compiler supports a given flag.
-# CHECK_CXX_COMPILER_FLAG(FLAG VARIABLE)
+# CHECK_CXX_COMPILER_FLAG(<flag> <var>)
-#
+#  <flag> - the compiler flag
-#  FLAG - the compiler flag
+#  <var>  - variable to store the result
-#  VARIABLE - variable to store the result
+# This internally calls the check_cxx_source_compiles macro.  See help
+# for CheckCXXSourceCompiles for a listing of variables that can
+# modify the build.
 
 # Copyright (c) 2006, Alexander Neundorf, <neundorf@kde.org>
 #

Modules/CheckCXXSourceCompiles.cmake

@@ -1,9 +1,7 @@
-# - Check if the C++ source code provided in the SOURCE argument compiles.
+# - Check if the given C++ source code compiles.
-# CHECK_CXX_SOURCE_COMPILES(SOURCE VAR)
+# CHECK_CXX_SOURCE_COMPILES(<code> <var>)
-#
+#  <code>       - source code to try to compile
-#  SOURCE - source code to try to compile
+#  <var>        - variable to store whether the source code compiled
-#  VAR    - variable to store whether the source code compiled
-#
 # The following variables may be set before calling this macro to
 # modify the way the check is run:
 #

Modules/CheckCXXSourceRuns.cmake

@@ -1,9 +1,8 @@
-# - Check if the C++ source code provided in the SOURCE argument compiles and runs.
+# - Check if the given C++ source code compiles and runs.
-# CHECK_CXX_SOURCE_RUNS(SOURCE VAR)
+# CHECK_CXX_SOURCE_RUNS(<code> <var>)
-#
+#  <code>   - source code to try to compile
-#  SOURCE - source code to try to compile
+#  <var>    - variable to store the result
-#  VAR    - variable to store the result, 1 for success, empty for failure
+#             (1 for success, empty for failure)
-#
 # The following variables may be set before calling this macro to
 # modify the way the check is run:
 #