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

Modules/readme.txt

@@ -57,7 +57,7 @@ For example:
 # - This is a cool module
 # This module does really cool stuff.
 # It can do even more than you think.
-# 
+#
 # It even needs to paragraphs to tell you about it.
 # And it defines the following variables:
 #  VAR_COOL - this is great isn't it?
@@ -119,17 +119,31 @@ able to find the package.  If the
 REQUIRED option is given to the command it will set the variable
 XXX_FIND_REQUIRED to true before loading the FindXXX.cmake module.  If
 this variable is set the module should issue a FATAL_ERROR if the
-package cannot be found.  For each package-specific component, say
-YYY, listed after the REQUIRED option a variable XXX_FIND_REQUIRED_YYY
-to true.  The set of components listed after either the REQUIRED
-option or the COMPONENTS option will be specified in a
-XXX_FIND_COMPONENTS variable.  This can be used by the FindXXX.cmake
-module to determine which sub-components of the package must be found.
+package cannot be found.
 If neither the QUIET nor REQUIRED options are given then the
 FindXXX.cmake module should look for the package and complain without
 error if the module is not found.
 
-To get this behaviour you can use the FIND_PACKAGE_HANDLE_STANDARD_ARGS() 
+A package can be provide sub-components.
+Those components can be listed after the COMPONENTS (or REQUIRED)
+or OPTIONAL_COMPONENTS keywords.  The set of all listed components will be
+specified in a XXX_FIND_COMPONENTS variable.
+For each package-specific component, say Yyy, a variable XXX_FIND_REQUIRED_Yyy
+will be set to true if it listed after COMPONENTS and it will be set to false
+if it was listed after OPTIONAL_COMPONENTS.
+Using those variables a FindXXX.cmake module and also a XXXConfig.cmake package
+configuration file can determine whether and which components have been requested,
+and whether they were requested as required or as optional.
+For each of the requested components a XXX_Yyy_FOUND variable should be set
+accordingly.
+The per-package XXX_FOUND variable should be only set to true if all requested
+required components have been found. A missing optional component should not
+keep the XXX_FOUND variable from being set to true.
+If the package provides XXX_INCLUDE_DIRS and XXX_LIBRARIES variables, the include
+dirs and libraries for all components which were requested and which have been
+found should be added to those two variables.
+
+To get this behaviour you can use the FIND_PACKAGE_HANDLE_STANDARD_ARGS()
 macro, as an example see FindJPEG.cmake.
 
 For internal implementation, it's a generally accepted convention that variables starting with

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.  "