From fb34f1d630f3c4f18389694fa5b1dc20a247ffe5 Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Sun, 16 Mar 2025 23:03:05 +0100
Subject: [PATCH] CMakeExpandImportedTargets: Update documentation

---
 Modules/CMakeExpandImportedTargets.cmake | 84 ++++++++++++++++--------
 1 file changed, 58 insertions(+), 26 deletions(-)

diff --git a/Modules/CMakeExpandImportedTargets.cmake b/Modules/CMakeExpandImportedTargets.cmake
index 4fad7f667c..64561e86d7 100644
--- a/Modules/CMakeExpandImportedTargets.cmake
+++ b/Modules/CMakeExpandImportedTargets.cmake
@@ -7,37 +7,69 @@ CMakeExpandImportedTargets
 
 .. deprecated:: 3.4
 
-  Do not use.
+  This module should no longer be used.
 
-This module was once needed to expand imported targets to the underlying
-libraries they reference on disk for use with the :command:`try_compile`
-and :command:`try_run` commands.  These commands now support imported
-libraries in their ``LINK_LIBRARIES`` options (since CMake 2.8.11
-for :command:`try_compile` and since CMake 3.2 for :command:`try_run`).
+  It was once needed to replace :ref:`Imported Targets` with their underlying
+  libraries referenced on disk for use with the :command:`try_compile` and
+  :command:`try_run` commands.  These commands now support imported targets in
+  their ``LINK_LIBRARIES`` options (since CMake 2.8.11 for
+  :command:`try_compile` command and since CMake 3.2 for :command:`try_run`
+  command).
 
-This module does not support the policy :policy:`CMP0022` ``NEW``
-behavior or use of the :prop_tgt:`INTERFACE_LINK_LIBRARIES` property
-because :manual:`generator expressions <cmake-generator-expressions(7)>`
-cannot be evaluated during configuration.
+.. note::
+
+  This module does not support the policy :policy:`CMP0022` ``NEW`` behavior,
+  nor does it use the :prop_tgt:`INTERFACE_LINK_LIBRARIES` property, because
+  :manual:`generator expressions <cmake-generator-expressions(7)>` cannot be
+  evaluated at the configuration phase.
+
+Functions
+^^^^^^^^^
+
+This module defines the following function:
+
+.. command:: cmake_expand_imported_targets
+
+  .. code-block:: cmake
+
+    cmake_expand_imported_targets(
+      <result-var>
+      LIBRARIES <libs>...
+      [CONFIGURATION <config>]
+    )
+
+  Expands all imported targets in a list of libraries ``<libs>...`` to their
+  corresponding file paths on disk and stores the resulting list in a local
+  variable ``<result-var>``.
+
+  The options are:
+
+  ``LIBRARIES``
+    A :ref:`semicolon-separated list <CMake Language Lists>` of system and
+    imported targets.  Imported targets in this list are replaced with their
+    corresponding library file paths, including libraries from their link
+    interfaces.
+
+  ``CONFIGURATION``
+    If this option is given, it uses the respective build configuration
+    ``<config>`` of the imported targets if it exists.  If omitted, it defaults
+    to the first entry in the :variable:`CMAKE_CONFIGURATION_TYPES` variable, or
+    falls back to :variable:`CMAKE_BUILD_TYPE` if ``CMAKE_CONFIGURATION_TYPES``
+    is not set.
+
+Examples
+^^^^^^^^
+
+Using this module to get a list of library paths:
 
 .. code-block:: cmake
 
- CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
-                               [CONFIGURATION <config>])
-
-CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
-all imported targets contained in this list with their actual file
-paths of the referenced libraries on disk, including the libraries
-from their link interfaces.  If a CONFIGURATION is given, it uses the
-respective configuration of the imported targets if it exists.  If no
-CONFIGURATION is given, it uses the first configuration from
-${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
-
-.. code-block:: cmake
-
-    cmake_expand_imported_targets(expandedLibs
-      LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
-      CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
+  include(CMakeExpandImportedTargets)
+  cmake_expand_imported_targets(
+    expandedLibs
+    LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
+    CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}"
+  )
 #]=======================================================================]
 
 function(CMAKE_EXPAND_IMPORTED_TARGETS _RESULT )