CheckTypeSize: Modernize and clarify documentation

Spell out the list of result variables as a definition list rather
than in prose.

Fixes: #23247

1 files changed, 36 insertions, 29 deletions

diff --git a/Modules/CheckTypeSize.cmake b/Modules/CheckTypeSize.cmake
index 69f68f9..602170c 100644
--- a/Modules/CheckTypeSize.cmake
+++ b/Modules/CheckTypeSize.cmake
@@ -7,46 +7,53 @@ CheckTypeSize
 
 Check sizeof a type
 
-.. command:: CHECK_TYPE_SIZE
+.. command:: check_type_size
 
   .. code-block:: cmake
 
-    CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
-                                  [LANGUAGE <language>])
+    check_type_size(<type> <variable> [BUILTIN_TYPES_ONLY]
+                                      [LANGUAGE <language>])
 
-  Check if the type exists and determine its size.  On return,
-  ``HAVE_${VARIABLE}`` holds the existence of the type, and ``${VARIABLE}``
-  holds one of the following:
+  Check if the type exists and determine its size.  Results are reported
+  in the following variables:
 
-  ::
+  ``HAVE_<variable>``
+    Holds a true or false value indicating whether the type exists.
 
-     <size> = type has non-zero size <size>
-     "0"    = type has arch-dependent size (see below)
-     ""     = type does not exist
+  ``<variable>``
+    Holds one of the following values:
 
-  Both ``HAVE_${VARIABLE}`` and ``${VARIABLE}`` will be created as internal
-  cache variables.
+    ``<size>``
+       Type has non-zero size ``<size>``.
 
-  Furthermore, the variable ``${VARIABLE}_CODE`` holds C preprocessor code
-  to define the macro ``${VARIABLE}`` to the size of the type, or leave
-  the macro undefined if the type does not exist.
+    ``0``
+       Type has architecture-dependent size.  This may occur when
+       :variable:`CMAKE_OSX_ARCHITECTURES` has multiple architectures.
+       In this case ``<variable>_CODE`` contains C preprocessor tests
+       mapping from each architecture macro to the corresponding type size.
+       The list of architecture macros is stored in ``<variable>_KEYS``,
+       and the value for each key is stored in ``<variable>-<key>``.
 
-  The variable ``${VARIABLE}`` may be ``0`` when
-  :variable:`CMAKE_OSX_ARCHITECTURES` has multiple architectures for building
-  OS X universal binaries.  This indicates that the type size varies across
-  architectures.  In this case ``${VARIABLE}_CODE`` contains C preprocessor
-  tests mapping from each architecture macro to the corresponding type size.
-  The list of architecture macros is stored in ``${VARIABLE}_KEYS``, and the
-  value for each key is stored in ``${VARIABLE}-${KEY}``.
+    "" (empty string)
+       Type does not exist.
 
-  If the ``BUILTIN_TYPES_ONLY`` option is not given, the macro checks for
-  headers ``<sys/types.h>``, ``<stdint.h>``, and ``<stddef.h>``, and saves
-  results in ``HAVE_SYS_TYPES_H``, ``HAVE_STDINT_H``, and ``HAVE_STDDEF_H``.
-  The type size check automatically includes the available headers, thus
-  supporting checks of types defined in the headers.
+  ``<variable>_CODE``
+    Holds C preprocessor code to define the macro ``<variable>`` to the size
+    of the type, or to leave the macro undefined if the type does not exist.
 
-  If ``LANGUAGE`` is set, the specified compiler will be used to perform the
-  check. Acceptable values are ``C`` and ``CXX``.
+  The options are:
+
+  ``BUILTIN_TYPES_ONLY``
+
+    Support only compiler-builtin types.  If *not* given, the macro checks
+    for headers ``<sys/types.h>``, ``<stdint.h>``, and ``<stddef.h>``, and
+    saves results in ``HAVE_SYS_TYPES_H``, ``HAVE_STDINT_H``, and
+    ``HAVE_STDDEF_H``.  The type size check automatically includes the
+    available headers, thus supporting checks of types defined in the headers.
+
+  ``LANGUAGE <language>``
+    Use the ``<language>`` compiler to perform the check.
+    Acceptable values are ``C`` and ``CXX``.
 
 Despite the name of the macro you may use it to check the size of more
 complex expressions, too.  To check e.g.  for the size of a struct