Help: Revise docs of modules AddFileDependencies..CheckFunctionExists

* Replace '::' by '.. code-block:: cmake' wherever it makes sense.
* Convert to definition list where appropriate.
* Prefer '<placeholder>' over 'placeholder'.

Modules/AddFileDependencies.cmake

@@ -5,9 +5,13 @@
 # AddFileDependencies
 # -------------------
 #
-# ADD_FILE_DEPENDENCIES(source_file depend_files...)
+# Add dependencies to a source file.
 #
-# Adds the given files as dependencies to source_file
+# .. code-block:: cmake
+#
+#   ADD_FILE_DEPENDENCIES(<source> <files>)
+#
+# Adds the given ``<files>`` to the dependencies of file ``<source>``.
 
 macro(ADD_FILE_DEPENDENCIES _file)
 

Modules/AndroidTestUtilities.cmake

@@ -40,7 +40,7 @@ Module Functions
 
 .. command:: android_add_test_data
 
-  ::
+  .. code-block:: cmake
 
     android_add_test_data(<test-name>
       [FILES <files>...] [FILES_DEST <device-dir>]

Modules/BundleUtilities.cmake

@@ -12,7 +12,7 @@ bundles on the Mac and bundle-like directories on any OS.
 
 The following functions are provided by this module:
 
-::
+.. code-block:: cmake
 
    fixup_bundle
    copy_and_fixup_bundle
@@ -39,7 +39,7 @@ DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from ``CMakeLists.txt``)!
 Instead, invoke them from an :command:`install(CODE)` or
 :command:`install(SCRIPT)` rule.
 
-::
+.. code-block:: cmake
 
   FIXUP_BUNDLE(<app> <libs> <dirs>)
 
@@ -62,14 +62,14 @@ ensure that it is truly standalone.
 As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
 which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
 
-::
+.. code-block:: cmake
 
   COPY_AND_FIXUP_BUNDLE(<src> <dst> <libs> <dirs>)
 
 Makes a copy of the bundle <src> at location <dst> and then fixes up
 the new copied bundle in-place at <dst>...
 
-::
+.. code-block:: cmake
 
   VERIFY_APP(<app>)
 
@@ -80,14 +80,14 @@ is not verified.
 As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
 which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
 
-::
+.. code-block:: cmake
 
   GET_BUNDLE_MAIN_EXECUTABLE(<bundle> <result_var>)
 
 The result will be the full path name of the bundle's main executable
 file or an "error:" prefixed string if it could not be determined.
 
-::
+.. code-block:: cmake
 
   GET_DOTAPP_DIR(<exe> <dotapp_dir_var>)
 
@@ -97,7 +97,7 @@ simply return the dir containing the executable.
 
 The returned directory may or may not exist.
 
-::
+.. code-block:: cmake
 
   GET_BUNDLE_AND_EXECUTABLE(<app> <bundle_var> <executable_var> <valid_var>)
 
@@ -106,14 +106,14 @@ nested inside a ".app" directory and returns the path to the ".app"
 directory in <bundle_var> and the path to its main executable in
 <executable_var>
 
-::
+.. code-block:: cmake
 
   GET_BUNDLE_ALL_EXECUTABLES(<bundle> <exes_var>)
 
 Scans the given bundle recursively for all executable files and
 accumulates them into a variable.
 
-::
+.. code-block:: cmake
 
   GET_ITEM_KEY(<item> <key_var>)
 
@@ -125,7 +125,7 @@ extension with "." replaced by "_"
 This key is used as a prefix for CMake variables so that we can
 associate a set of variables with a given item based on its key.
 
-::
+.. code-block:: cmake
 
   CLEAR_BUNDLE_KEYS(<keys_var>)
 
@@ -135,7 +135,7 @@ each key.  After the loop, clear the list of keys itself.
 Caller of get_bundle_keys should call clear_bundle_keys when done with
 list of keys.
 
-::
+.. code-block:: cmake
 
   SET_BUNDLE_KEY_VALUES(<keys_var> <context> <item> <exepath> <dirs>
                         <copyflag> [<rpaths>])
@@ -143,7 +143,7 @@ list of keys.
 Add a key to the list (if necessary) for the given item.  If added,
 also set all the variables associated with that key.
 
-::
+.. code-block:: cmake
 
   GET_BUNDLE_KEYS(<app> <libs> <dirs> <keys_var>)
 
@@ -156,7 +156,7 @@ appropriate install_name_tool fixups.
 As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
 which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
 
-::
+.. code-block:: cmake
 
   COPY_RESOLVED_ITEM_INTO_BUNDLE(<resolved_item> <resolved_embedded_item>)
 
@@ -164,7 +164,7 @@ Copy a resolved item into the bundle if necessary.  Copy is not
 necessary if the resolved_item is "the same as" the
 resolved_embedded_item.
 
-::
+.. code-block:: cmake
 
   COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE(<resolved_item> <resolved_embedded_item>)
 
@@ -178,7 +178,7 @@ BU_COPY_FULL_FRAMEWORK_CONTENTS to ON before calling fixup_bundle.  By
 default, COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE copies the framework
 dylib itself plus the framework Resources directory.
 
-::
+.. code-block:: cmake
 
   FIXUP_BUNDLE_ITEM(<resolved_embedded_item> <exepath> <dirs>)
 
@@ -204,7 +204,7 @@ once.
 If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be
 marked writable before install_name_tool tries to change them.
 
-::
+.. code-block:: cmake
 
   VERIFY_BUNDLE_PREREQUISITES(<bundle> <result_var> <info_var>)
 
@@ -215,7 +215,7 @@ presumed to exist everywhere.
 As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
 which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
 
-::
+.. code-block:: cmake
 
   VERIFY_BUNDLE_SYMLINKS(<bundle> <result_var> <info_var>)
 

Modules/CheckCCompilerFlag.cmake

@@ -9,7 +9,7 @@ Check whether the C compiler supports a given flag.
 
 .. command:: check_c_compiler_flag
 
-  ::
+  .. code-block:: cmake
 
     check_c_compiler_flag(<flag> <var>)
 

Modules/CheckCSourceCompiles.cmake

@@ -9,15 +9,16 @@ Check if given C source compiles and links into an executable.
 
 .. command:: check_c_source_compiles
 
-  ::
+  .. code-block:: cmake
 
-    check_c_source_compiles(code resultVar [FAIL_REGEX regex1 [regex2...]])
+    check_c_source_compiles(<code> <resultVar>
+                            [FAIL_REGEX <regex1> [<regex2>...]])
 
-  Check that the source supplied in ``code`` can be compiled as a C source
+  Check that the source supplied in ``<code>`` can be compiled as a C source
   file and linked as an executable (so it must contain at least a ``main()``
   function). The result will be stored in the internal cache variable specified
-  by ``resultVar``, with a boolean true value for success and boolean false for
+  by ``<resultVar>``, with a boolean true value for success and boolean false
-  failure. If ``FAIL_REGEX`` is provided, then failure is determined by
+  for failure. If ``FAIL_REGEX`` is provided, then failure is determined by
   checking if anything in the output matches any of the specified regular
   expressions.
 
@@ -34,7 +35,7 @@ Check if given C source compiles and links into an executable.
   ``CMAKE_REQUIRED_DEFINITIONS``
     A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
     ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
-    ``resultVar`` will also be added automatically.
+    ``<resultVar>`` will also be added automatically.
 
   ``CMAKE_REQUIRED_INCLUDES``
     A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
@@ -53,10 +54,10 @@ Check if given C source compiles and links into an executable.
     associated with the check will be suppressed.
 
   The check is only performed once, with the result cached in the variable
-  named by ``resultVar``. Every subsequent CMake run will re-use this cached
+  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
-  value rather than performing the check again, even if the ``code`` changes.
+  value rather than performing the check again, even if the ``<code>`` changes.
   In order to force the check to be re-evaluated, the variable named by
-  ``resultVar`` must be manually removed from the cache.
+  ``<resultVar>`` must be manually removed from the cache.
 
 #]=======================================================================]
 
@@ -131,4 +132,3 @@ macro(CHECK_C_SOURCE_COMPILES SOURCE VAR)
     endif()
   endif()
 endmacro()
-

Modules/CheckCSourceRuns.cmake

@@ -10,16 +10,16 @@ subsequently be run.
 
 .. command:: check_c_source_runs
 
-  ::
+  .. code-block:: cmake
 
-    check_c_source_runs(code resultVar)
+    check_c_source_runs(<code> <resultVar>)
 
-  Check that the source supplied in ``code`` can be compiled as a C source
+  Check that the source supplied in ``<code>`` can be compiled as a C source
-  file, linked as an executable and then run. The ``code`` must contain at
+  file, linked as an executable and then run. The ``<code>`` must contain at
-  least a ``main()`` function. If the code could be built and run successfully,
+  least a ``main()`` function. If the ``<code>`` could be built and run
-  the internal cache variable specified by ``resultVar`` will be set to 1,
+  successfully, the internal cache variable specified by ``<resultVar>`` will
-  otherwise it will be set to an value that evaluates to boolean false (e.g.
+  be set to 1, otherwise it will be set to an value that evaluates to boolean
-  an empty string or an error message).
+  false (e.g. an empty string or an error message).
 
   The underlying check is performed by the :command:`try_run` command. The
   compile and link commands can be influenced by setting any of the following
@@ -34,7 +34,7 @@ subsequently be run.
   ``CMAKE_REQUIRED_DEFINITIONS``
     A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
     ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
-    ``resultVar`` will also be added automatically.
+    ``<resultVar>`` will also be added automatically.
 
   ``CMAKE_REQUIRED_INCLUDES``
     A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
@@ -53,10 +53,10 @@ subsequently be run.
     associated with the check will be suppressed.
 
   The check is only performed once, with the result cached in the variable
-  named by ``resultVar``. Every subsequent CMake run will re-use this cached
+  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
-  value rather than performing the check again, even if the ``code`` changes.
+  value rather than performing the check again, even if the ``<code>`` changes.
   In order to force the check to be re-evaluated, the variable named by
-  ``resultVar`` must be manually removed from the cache.
+  ``<resultVar>`` must be manually removed from the cache.
 
 #]=======================================================================]
 
@@ -132,4 +132,3 @@ macro(CHECK_C_SOURCE_RUNS SOURCE VAR)
     endif()
   endif()
 endmacro()
-

Modules/CheckCXXCompilerFlag.cmake

@@ -9,7 +9,7 @@ Check whether the CXX compiler supports a given flag.
 
 .. command:: check_cxx_compiler_flag
 
-  ::
+  .. code-block:: cmake
 
     check_cxx_compiler_flag(<flag> <var>)
 
@@ -61,4 +61,3 @@ macro (CHECK_CXX_COMPILER_FLAG _FLAG _RESULT)
 
    set (CMAKE_REQUIRED_DEFINITIONS "${SAFE_CMAKE_REQUIRED_DEFINITIONS}")
 endmacro ()
-

Modules/CheckCXXSourceCompiles.cmake

@@ -9,15 +9,16 @@ Check if given C++ source compiles and links into an executable.
 
 .. command:: check_cxx_source_compiles
 
-  ::
+  .. code-block:: cmake
 
-    check_cxx_source_compiles(code resultVar [FAIL_REGEX regex1 [regex2...]])
+    check_cxx_source_compiles(<code> <resultVar>
+                              [FAIL_REGEX <regex1> [<regex2>...]])
 
-  Check that the source supplied in ``code`` can be compiled as a C++ source
+  Check that the source supplied in ``<code>`` can be compiled as a C++ source
   file and linked as an executable (so it must contain at least a ``main()``
   function). The result will be stored in the internal cache variable specified
-  by ``resultVar``, with a boolean true value for success and boolean false for
+  by ``<resultVar>``, with a boolean true value for success and boolean false
-  failure. If ``FAIL_REGEX`` is provided, then failure is determined by
+  for failure. If ``FAIL_REGEX`` is provided, then failure is determined by
   checking if anything in the output matches any of the specified regular
   expressions.
 
@@ -34,7 +35,7 @@ Check if given C++ source compiles and links into an executable.
   ``CMAKE_REQUIRED_DEFINITIONS``
     A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
     ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
-    ``resultVar`` will also be added automatically.
+    ``<resultVar>`` will also be added automatically.
 
   ``CMAKE_REQUIRED_INCLUDES``
     A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
@@ -53,10 +54,10 @@ Check if given C++ source compiles and links into an executable.
     associated with the check will be suppressed.
 
   The check is only performed once, with the result cached in the variable
-  named by ``resultVar``. Every subsequent CMake run will re-use this cached
+  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
-  value rather than performing the check again, even if the ``code`` changes.
+  value rather than performing the check again, even if the ``<code>`` changes.
   In order to force the check to be re-evaluated, the variable named by
-  ``resultVar`` must be manually removed from the cache.
+  ``<resultVar>`` must be manually removed from the cache.
 
 #]=======================================================================]
 
@@ -132,4 +133,3 @@ macro(CHECK_CXX_SOURCE_COMPILES SOURCE VAR)
     endif()
   endif()
 endmacro()
-

Modules/CheckCXXSourceRuns.cmake

@@ -10,16 +10,16 @@ subsequently be run.
 
 .. command:: check_cxx_source_runs
 
-  ::
+  .. code-block:: cmake
 
-    check_cxx_source_runs(code resultVar)
+    check_cxx_source_runs(<code> <resultVar>)
 
-  Check that the source supplied in ``code`` can be compiled as a C++ source
+  Check that the source supplied in ``<code>`` can be compiled as a C++ source
-  file, linked as an executable and then run. The ``code`` must contain at
+  file, linked as an executable and then run. The ``<code>`` must contain at
-  least a ``main()`` function. If the code could be built and run successfully,
+  least a ``main()`` function. If the ``<code>`` could be built and run
-  the internal cache variable specified by ``resultVar`` will be set to 1,
+  successfully, the internal cache variable specified by ``<resultVar>`` will
-  otherwise it will be set to an value that evaluates to boolean false (e.g.
+  be set to 1, otherwise it will be set to an value that evaluates to boolean
-  an empty string or an error message).
+  false (e.g. an empty string or an error message).
 
   The underlying check is performed by the :command:`try_run` command. The
   compile and link commands can be influenced by setting any of the following
@@ -34,7 +34,7 @@ subsequently be run.
   ``CMAKE_REQUIRED_DEFINITIONS``
     A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
     ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
-    ``resultVar`` will also be added automatically.
+    ``<resultVar>`` will also be added automatically.
 
   ``CMAKE_REQUIRED_INCLUDES``
     A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
@@ -53,10 +53,10 @@ subsequently be run.
     associated with the check will be suppressed.
 
   The check is only performed once, with the result cached in the variable
-  named by ``resultVar``. Every subsequent CMake run will re-use this cached
+  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
-  value rather than performing the check again, even if the ``code`` changes.
+  value rather than performing the check again, even if the ``<code>`` changes.
   In order to force the check to be re-evaluated, the variable named by
-  ``resultVar`` must be manually removed from the cache.
+  ``<resultVar>`` must be manually removed from the cache.
 
 #]=======================================================================]
 
@@ -127,4 +127,3 @@ macro(CHECK_CXX_SOURCE_RUNS SOURCE VAR)
     endif()
   endif()
 endmacro()
-

Modules/CheckCXXSymbolExists.cmake

@@ -7,10 +7,12 @@
 #
 # Check if a symbol exists as a function, variable, or macro in C++
 #
-# CHECK_CXX_SYMBOL_EXISTS(<symbol> <files> <variable>)
+# .. code-block:: cmake
 #
-# Check that the <symbol> is available after including given header
+#   CHECK_CXX_SYMBOL_EXISTS(<symbol> <files> <variable>)
-# <files> and store the result in a <variable>.  Specify the list of
+#
+# Check that the ``<symbol>`` is available after including given header
+# ``<files>`` and store the result in a ``<variable>``.  Specify the list of
 # files in one argument as a semicolon-separated list.
 # CHECK_CXX_SYMBOL_EXISTS() can be used to check in C++ files, as
 # opposed to CHECK_SYMBOL_EXISTS(), which works only for C.
@@ -24,13 +26,16 @@
 # 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_FLAGS = string of compile command line flags
+# ``CMAKE_REQUIRED_DEFINITIONS``
-#   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
+#    list of macros to define (-DFOO=bar)
-#   CMAKE_REQUIRED_INCLUDES = list of include directories
+# ``CMAKE_REQUIRED_INCLUDES``
-#   CMAKE_REQUIRED_LIBRARIES = list of libraries to link
+#    list of include directories
-#   CMAKE_REQUIRED_QUIET = execute quietly without messages
+# ``CMAKE_REQUIRED_LIBRARIES``
+#    list of libraries to link
+# ``CMAKE_REQUIRED_QUIET``
+#    execute quietly without messages
 
 include_guard(GLOBAL)
 include(CheckSymbolExists)

Modules/CheckFortranCompilerFlag.cmake

@@ -9,7 +9,7 @@ Check whether the Fortran compiler supports a given flag.
 
 .. command:: check_fortran_compiler_flag
 
-  ::
+  .. code-block:: cmake
 
     check_fortran_compiler_flag(<flag> <var>)
 

Modules/CheckFortranFunctionExists.cmake

@@ -5,24 +5,24 @@
 # CheckFortranFunctionExists
 # --------------------------
 #
-# macro which checks if the Fortran function exists
+# :command:`Macro <macro>` which checks if a Fortran function exists.
 #
-# CHECK_FORTRAN_FUNCTION_EXISTS(FUNCTION VARIABLE)
+# .. code-block:: cmake
 #
-# ::
+#   CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)
-#
-#   FUNCTION - the name of the Fortran function
-#   VARIABLE - variable to store the result
-#              Will be created as an internal cache variable.
 #
+# where
 #
+# ``<function>``
+#   the name of the Fortran function
+# ``<result>``
+#   variable to store the result; will be created as an internal cache variable.
 #
 # The following variables may be set before calling this macro to modify
 # the way the check is run:
 #
-# ::
+# ``CMAKE_REQUIRED_LIBRARIES``
-#
+#   list of libraries to link
-#   CMAKE_REQUIRED_LIBRARIES = list of libraries to link
 
 include_guard(GLOBAL)
 

Modules/CheckFortranSourceCompiles.cmake

@@ -9,23 +9,24 @@ Check if given Fortran source compiles and links into an executable.
 
 .. command:: check_fortran_source_compiles
 
-  ::
+  .. code-block:: cmake
 
-    check_fortran_source_compiles(code resultVar
+    check_fortran_source_compiles(<code> <resultVar>
-        [FAIL_REGEX regex1 [regex2...]]
+        [FAIL_REGEX <regex>...]
-        [SRC_EXT ext]
+        [SRC_EXT <extension>]
     )
 
-  Check that the source supplied in ``code`` can be compiled as a Fortran
+  Checks that the source supplied in ``<code>`` can be compiled as a Fortran
   source file and linked as an executable (so it must contain at least a
   ``PROGRAM`` entry point). The result will be stored in the internal cache
-  variable specified by ``resultVar``, with a boolean true value for success
+  variable ``<resultVar>``, with a boolean true value for success and boolean
-  and boolean false for failure. If ``FAIL_REGEX`` is provided, then failure is
+  false for failure.
-  determined by checking if anything in the output matches any of the specified
+
-  regular expressions.
+  If ``FAIL_REGEX`` is provided, then failure is determined by checking
+  if anything in the output matches any of the specified regular expressions.
 
   By default, the test source file will be given a ``.F`` file extension. The
-  ``SRC_EXT`` option can be used to override this with ``.ext`` instead.
+  ``SRC_EXT`` option can be used to override this with ``.<extension>`` instead.
 
   The underlying check is performed by the :command:`try_compile` command. The
   compile and link commands can be influenced by setting any of the following
@@ -40,7 +41,7 @@ Check if given Fortran source compiles and links into an executable.
   ``CMAKE_REQUIRED_DEFINITIONS``
     A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
     ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
-    ``resultVar`` will also be added automatically.
+    ``<resultVar>`` will also be added automatically.
 
   ``CMAKE_REQUIRED_INCLUDES``
     A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
@@ -59,10 +60,10 @@ Check if given Fortran source compiles and links into an executable.
     associated with the check will be suppressed.
 
   The check is only performed once, with the result cached in the variable
-  named by ``resultVar``. Every subsequent CMake run will re-use this cached
+  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
-  value rather than performing the check again, even if the ``code`` changes.
+  value rather than performing the check again, even if the ``<code>`` changes.
   In order to force the check to be re-evaluated, the variable named by
-  ``resultVar`` must be manually removed from the cache.
+  ``<resultVar>`` must be manually removed from the cache.
 
 #]=======================================================================]
 

Modules/CheckFunctionExists.cmake

@@ -5,24 +5,29 @@
 # CheckFunctionExists
 # -------------------
 #
-# Check if a C function can be linked::
+# Check if a C function can be linked
+#
+# .. code-block:: cmake
 #
 #   check_function_exists(<function> <variable>)
 #
-# Check that the ``<function>`` is provided by libraries on the system and store
+# Checks that the ``<function>`` is provided by libraries on the system and store
-# the result in a ``<variable>``. ``<variable>`` will be created as an internal
+# the result in a ``<variable>``, which will be created as an internal
 # cache variable.
 #
 # 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_FLAGS = string of compile command line flags
+# ``CMAKE_REQUIRED_DEFINITIONS``
-#   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
+#   list of macros to define (-DFOO=bar)
-#   CMAKE_REQUIRED_INCLUDES = list of include directories
+# ``CMAKE_REQUIRED_INCLUDES``
-#   CMAKE_REQUIRED_LIBRARIES = list of libraries to link
+#   list of include directories
-#   CMAKE_REQUIRED_QUIET = execute quietly without messages
+# ``CMAKE_REQUIRED_LIBRARIES``
+#   list of libraries to link
+# ``CMAKE_REQUIRED_QUIET``
+#   execute quietly without messages
 #
 # .. note::
 #