CheckIPOSupported: Extend documentation

- Added intro code block showing how to include this module.
- Added brief description about IPO and LTO and how it is enabled in
  CMake.
- Used "command" instead of "function".
- Reworded few descriptions.
- Synced indentation for items related to the command section.
- Added "See Also" sections to related target properties and variables.

Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst

@@ -15,3 +15,9 @@ target is created.
 There is also the per-configuration :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>`
 target property, which overrides :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`
 if it is set.
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckIPOSupported` module to check whether the compiler
+  supports interprocedural optimization before enabling this target property.

Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst

@@ -10,3 +10,9 @@ configuration.
 This property is initialized by the
 :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` variable if it is set
 when a target is created.
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckIPOSupported` module to check whether the compiler
+  supports interprocedural optimization before enabling this target property.

Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst

@@ -8,3 +8,8 @@ Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` of targets.
 This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`
 property on all the targets.  See that target property for additional
 information.
+
+See Also
+^^^^^^^^
+
+* The :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` variable.

Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst

@@ -8,3 +8,8 @@ Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` of targets.
 This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>`
 property on all the targets.  See that target property for additional
 information.
+
+See Also
+^^^^^^^^
+
+* The :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable.

Modules/CheckIPOSupported.cmake

@@ -7,25 +7,56 @@ CheckIPOSupported
 
 .. versionadded:: 3.9
 
-This module provides a function to check whether the compiler supports an
+This module provides a command to check whether the compiler supports
-interprocedural optimization (IPO/LTO).  Use this module before enabling the
+interprocedural optimization (IPO/LTO).
-:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckIPOSupported)
+
+Interprocedural optimization is a compiler technique that performs
+optimizations across translation units (i.e., across source files), allowing
+the compiler to analyze and optimize the entire program as a whole rather
+than file-by-file.  This can improve performance by enabling more aggressive
+inlining and dead code elimination.  When these optimizations are applied at
+link time, the process is typically referred to as link-time optimization
+(LTO), which is a common form of IPO.
+
+In CMake, interprocedural optimization can be enabled on a per-target basis
+using the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property, or
+for all targets in the current scope using the
+:variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable.
+
+Use this module before enabling the interprocedural optimization on targets
+to ensure the compiler supports IPO/LTO.
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_ipo_supported
 
+  Checks whether the compiler supports interprocedural optimization (IPO/LTO):
+
   .. code-block:: cmake
 
-    check_ipo_supported([RESULT <result>] [OUTPUT <output>]
+    check_ipo_supported(
-                        [LANGUAGES <lang>...])
+      [RESULT <result-var>]
+      [OUTPUT <output-var>]
+      [LANGUAGES <lang>...]
+    )
 
   Options are:
 
-  ``RESULT <result>``
+  ``RESULT <result-var>``
-    Set ``<result>`` variable to ``YES`` if IPO is supported by the
+    Set ``<result-var>`` variable to ``YES`` if IPO is supported by the
     compiler and ``NO`` otherwise.  If this option is not given then
     the command will issue a fatal error if IPO is not supported.
-  ``OUTPUT <output>``
+  ``OUTPUT <output-var>``
-    Set ``<output>`` variable with details about any error.
+    Set ``<output-var>`` variable with details about any error.
   ``LANGUAGES <lang>...``
     Specify languages whose compilers to check.
 
@@ -44,18 +75,18 @@ interprocedural optimization (IPO/LTO).  Use this module before enabling the
     If this option is not given, the default languages are picked from
     the current :prop_gbl:`ENABLED_LANGUAGES` global property.
 
-.. note::
+  .. note::
 
-  To use ``check_ipo_supported()``, policy :policy:`CMP0069` must be set to
+    To use ``check_ipo_supported()``, policy :policy:`CMP0069` must be set to
-  ``NEW``; otherwise, a fatal error will occur.
+    ``NEW``; otherwise, a fatal error will occur.
 
-.. versionadded:: 3.13
+  .. versionadded:: 3.13
-  Support for Visual Studio generators.
+    Support for Visual Studio generators.
 
-.. versionadded:: 3.24
+  .. versionadded:: 3.24
-  The check uses the caller's :variable:`CMAKE_<LANG>_FLAGS`
+    The check uses the caller's :variable:`CMAKE_<LANG>_FLAGS`
-  and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values.
+    and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values.
-  See policy :policy:`CMP0138`.
+    See policy :policy:`CMP0138`.
 
 Examples
 ^^^^^^^^
@@ -69,10 +100,10 @@ not supported:
   check_ipo_supported() # fatal error if IPO is not supported
   set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
 
-The following example demonstrates how to use the ``CheckIPOSupported`` module
+The following example demonstrates how to use this module to enable IPO for
-to enable IPO for the target only when supported by the compiler and to issue a
+the target only when supported by the compiler and to issue a warning if it
-warning if it is not.  Additionally, projects may want to provide a
+is not.  Additionally, projects may want to provide a configuration option
-configuration option to control when IPO is enabled.  For example:
+to control when IPO is enabled.  For example:
 
 .. code-block:: cmake