find_package: add documentation for OPTIONAL_COMPONENTS

This patch adds documentation for OPTIONAL_COMPONENTS to cmFindPackage.cxx,
and also extends Modules/readme.txt significantly with regard to how
components should be handled.

Alex

1 files changed, 9 insertions, 4 deletions

diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index b9872e9..ef16ce8 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -90,6 +90,7 @@ void cmFindPackageCommand::GenerateDocumentation()
   this->CommandDocumentation =
     "  find_package(<package> [version] [EXACT] [QUIET] [MODULE]\n"
     "               [[REQUIRED|COMPONENTS] [components...]]\n"
+    "               [OPTIONAL_COMPONENTS components...]\n"
     "               [NO_POLICY_SCOPE])\n"
     "Finds and loads settings from an external project.  "
     "<package>_FOUND will be set to indicate whether the package was found.  "
@@ -98,10 +99,14 @@ void cmFindPackageCommand::GenerateDocumentation()
     "The QUIET option disables messages if the package cannot be found.  "
     "The MODULE option disables the second signature documented below.  "
     "The REQUIRED option stops processing with an error message if the "
-    "package cannot be found.  "
-    "A package-specific list of components may be listed after the "
-    "REQUIRED option or after the COMPONENTS option if no REQUIRED "
-    "option is given.  "
+    "package cannot be found."
+    "\n"
+    "A package-specific list of required components may be listed after the "
+    "COMPONENTS option or directly after the REQUIRED option.  "
+    "Additional optional components may be listed after OPTIONAL_COMPONENTS.  "
+    "Available components and their influence on whether a package is "
+    "considered to be found are defined by the target package."
+    "\n"
     "The [version] argument requests a version with which the package found "
     "should be compatible (format is major[.minor[.patch[.tweak]]]).  "
     "The EXACT option requests that the version be matched exactly.  "