From ee398e8946e8db058dcb45c956b5a4d1d54a362b Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Sat, 8 Mar 2025 06:03:49 +0100
Subject: [PATCH] FindPackageMessage: Update documentation

- Documentation updated.
- This module is internally already used by the
  FindPackageHandleStandardArgs module and can conflict when used again
  in the find module due to the same <PackageName> used, or when QUIET
  option is used. For this reason, the example is changed and explained
  at the bottom to use find_package_handle_standard_args().
- Lower-case style function used in FindPackageHandleStandardArgs.
---
 Modules/FindPackageHandleStandardArgs.cmake |  2 +-
 Modules/FindPackageMessage.cmake            | 76 +++++++++++++++++----
 2 files changed, 62 insertions(+), 16 deletions(-)

diff --git a/Modules/FindPackageHandleStandardArgs.cmake b/Modules/FindPackageHandleStandardArgs.cmake
index c2eeb49ba2..508193647f 100644
--- a/Modules/FindPackageHandleStandardArgs.cmake
+++ b/Modules/FindPackageHandleStandardArgs.cmake
@@ -569,7 +569,7 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
 
   # print the result:
   if(${_NAME}_FOUND)
-    FIND_PACKAGE_MESSAGE(${_NAME} "Found ${_NAME}: ${${_FIRST_REQUIRED_VAR}} ${VERSION_MSG} ${COMPONENT_MSG}" "${DETAILS}")
+    find_package_message(${_NAME} "Found ${_NAME}: ${${_FIRST_REQUIRED_VAR}} ${VERSION_MSG} ${COMPONENT_MSG}" "${DETAILS}")
   else()
 
     if(FPHSA_CONFIG_MODE)
diff --git a/Modules/FindPackageMessage.cmake b/Modules/FindPackageMessage.cmake
index a9f2d2b40b..27f15147a2 100644
--- a/Modules/FindPackageMessage.cmake
+++ b/Modules/FindPackageMessage.cmake
@@ -5,29 +5,75 @@
 FindPackageMessage
 ------------------
 
-.. code-block:: cmake
+This module is intended to be used in
+:ref:`FindXXX.cmake modules <Find Modules>` and provides a function for printing
+find result messages.
 
-  find_package_message(<name> "message for user" "find result details")
+.. command:: find_package_message
 
-This function is intended to be used in FindXXX.cmake modules files.
-It will print a message once for each unique find result.  This is
-useful for telling the user where a package was found.  The first
-argument specifies the name (XXX) of the package.  The second argument
-specifies the message to display.  The third argument lists details
-about the find result so that if they change the message will be
-displayed again.  The macro also obeys the QUIET argument to the
-find_package command.
+  .. code-block:: cmake
 
-Example:
+    find_package_message(<PackageName> <message> <details>)
+
+  Prints a ``<message>`` once for each unique find result to inform the user
+  which package was found and where.
+
+  ``<PackageName>``
+    The name of the package (for example, as used in the
+    ``Find<PackageName>.cmake`` module filename).
+
+  ``<message>``
+    The message string to display.
+
+  ``<details>``
+    A unique identifier for tracking message display.  The ``<message>`` is
+    printed only once per distinct ``<details>`` value.  If ``<details>`` string
+    changes in a subsequent configuration phase, the message will be displayed
+    again.
+
+  If :command:`find_package` was called with the ``QUIET`` option, the
+  ``<message>`` is not printed.
+
+Examples
+^^^^^^^^
+
+Printing result message in a find module:
 
 .. code-block:: cmake
+  :caption: FindFoo.cmake
 
-  if(X11_FOUND)
-    find_package_message(X11 "Found X11: ${X11_X11_LIB}"
-      "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
+  find_library(Foo_LIBRARY foo)
+  find_path(Foo_INCLUDE_DIR foo.h)
+
+  # ...
+
+  include(FindPackageMessage)
+
+  if(Foo_FOUND)
+    find_package_message(
+      Foo
+      "Found Foo: ${Foo_LIBRARY}"
+      "[${Foo_LIBRARY}][${Foo_INCLUDE_DIR}]"
+    )
   else()
-   ...
+    # ...
   endif()
+
+When writing standard :ref:`Find modules <Find Modules>`, use the
+:module:`find_package_handle_standard_args() <FindPackageHandleStandardArgs>`
+function, which automatically prints the find result message:
+
+.. code-block:: cmake
+  :caption: FindFoo.cmake
+
+  # ...
+
+  include(FindPackageHandleStandardArgs)
+
+  find_package_handle_standard_args(
+    Foo
+    REQUIRED_VARS Foo_LIBRARY Foo_INCLUDE_DIR
+  )
 #]=======================================================================]
 
 function(find_package_message pkg msg details)