Improve ECMPackageConfigHelpers documentation.

In particular, strongly recommend looking at the equivalent CMake
documentation with regard to PATH_VARS, as a lot of projects that should
be making use of it are not.

1 files changed, 20 insertions, 11 deletions

diff --git a/modules/ECMPackageConfigHelpers.cmake b/modules/ECMPackageConfigHelpers.cmake
index 6e69fb80..d1d0408f 100644
--- a/modules/ECMPackageConfigHelpers.cmake
+++ b/modules/ECMPackageConfigHelpers.cmake
@@ -5,7 +5,9 @@
 # Helper macros for generating CMake package config files.
 #
 # ``write_basic_package_version_file()`` is the same as the one provided by the
-# CMakePackageConfigHelpers module in CMake; see that module's documentation for
+# `CMakePackageConfigHelpers
+# <http://www.cmake.org/cmake/help/v2.8.12/cmake.html#module:CMakePackageConfigHelpers>`_
+# module in CMake; see that module's documentation for
 # more information.
 #
 # ::
@@ -18,7 +20,23 @@
 #
 #
 # This behaves in the same way as configure_package_config_file() from CMake
-# 2.8.12, except that it adds an extra helper macro: find_dependency().
+# 2.8.12, except that it adds an extra helper macro: find_dependency(). It is
+# highly recommended that you read the `documentation for
+# CMakePackageConfigHelpers
+# <http://www.cmake.org/cmake/help/v2.8.12/cmake.html#module:CMakePackageConfigHelpers>`_
+# for more information, particularly with regard to the PATH_VARS argument.
+#
+# Note that there is no argument that will disable the find_dependency() macro;
+# if you do not require this macro, you should use
+# ``configure_package_config_file`` from the CMakePackageConfigHelpers module.
+#
+# CMake 3.0 includes a CMakeFindDependencyMacro module that provides the
+# find_dependency() macro (which you can ``include()`` in your package config
+# file), so this file is only useful for projects wishing to provide config
+# files that will work with CMake 2.8.12.
+#
+# Additional Config File Macros
+# =============================
 #
 # ::
 #
@@ -29,15 +47,6 @@
 # REQUIRED which were passed to the original find_package() call.  It also sets
 # an informative diagnostic message if the dependency could not be found.
 #
-# Note that there is no argument to disable the find_dependency() macro; if you
-# do not require this macro, you should just use the CMakeFindDependencyMacro
-# module directly.
-#
-# CMake 3.0.0 will include a CMakeFindDependencyMacro module that will provide
-# the find_dependency() macro (which you can include() in your package config
-# file), so this file is only useful for projects whose minimum required version
-# is 2.8.12.
-#
 # Since pre-1.0.0.
 
 #=============================================================================