CMakeFindDependencyMacro: Document return() behavior and caveats

The `find_dependency` macro is designed to be called from Package
Configuration Files, not from Find Modules.  The return() behavior is
particularly problematic for find modules.  Document this more clearly.

Issue: #17257

1 files changed, 18 insertions, 7 deletions

diff --git a/Modules/CMakeFindDependencyMacro.cmake b/Modules/CMakeFindDependencyMacro.cmake
index 0ad4531508..6a89fff2ae 100644
--- a/Modules/CMakeFindDependencyMacro.cmake
+++ b/Modules/CMakeFindDependencyMacro.cmake
@@ -5,18 +5,29 @@
 CMakeFindDependencyMacro
 -------------------------
 
-::
+.. command:: find_dependency
+
+  The ``find_dependency()`` macro wraps a :command:`find_package` call for
+  a package dependency::
 
     find_dependency(<dep> [...])
 
+  It is designed to be used in a
+  :ref:`Package Configuration File <Config File Packages>`
+  (``<package>Config.cmake``).  ``find_dependency`` forwards the correct
+  parameters for ``QUIET`` and ``REQUIRED`` which were passed to
+  the original :command:`find_package` call.  Any additional arguments
+  specified are forwarded to :command:`find_package`.
+
+  If the dependency could not be found it sets an informative diagnostic
+  message and calls :command:`return` to end processing of the calling
+  package configuration file and return to the :command:`find_package`
+  command that loaded it.
 
-``find_dependency()`` wraps a :command:`find_package` call for a package
-dependency. It is designed to be used in a <package>Config.cmake file, and it
-forwards the correct parameters for QUIET and REQUIRED which were passed to
-the original :command:`find_package` call.  It also sets an informative
-diagnostic message if the dependency could not be found.
+  .. note::
 
-Any additional arguments specified are forwarded to :command:`find_package`.
+    The call to :command:`return` makes this macro unsuitable to call
+    from :ref:`Find Modules`.
 #]=======================================================================]
 
 macro(find_dependency dep)