Merge topic 'patch-FindPackageMessage'

ee398e8946 FindPackageMessage: Update documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10441

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)

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.
+
+.. command:: find_package_message
+
+  .. code-block:: cmake
+
+    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.
 
-  find_package_message(<name> "message for user" "find result details")
+  ``<PackageName>``
+    The name of the package (for example, as used in the
+    ``Find<PackageName>.cmake`` module filename).
 
-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.
+  ``<message>``
+    The message string to display.
 
-Example:
+  ``<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
+
+  find_library(Foo_LIBRARY foo)
+  find_path(Foo_INCLUDE_DIR foo.h)
 
-  if(X11_FOUND)
-    find_package_message(X11 "Found X11: ${X11_X11_LIB}"
-      "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
+  # ...
+
+  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)