ENH: Documentation improvements.

Source/cmFindFileCommand.h

@@ -69,15 +69,16 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  FIND_FILE(VAR fileName path1 path2 ... [DOC docstring])\n"
-      "If the file is found, then VAR is set to the path where it was found.  "
-      "A cache entry named by VAR is created to "
-      "store the result.  VAR-NOTFOUND is the value used if the file was "
-      "not found.  CMake will continue to look as long as the value "
-      "is not found.  If DOC is specified the next argument is the "
-      "documentation string for the cache entry VAR.  Since Executables "
-      "can have different extensions on different platforms, FIND_PROGRAM "
-      "should be used instead of FIND_FILE when looking for and executable.";
+      "  FIND_FILE(<VAR> fileName path1 [path2 ...]\n"
+      "            [DOC \"docstring\"])\n"
+      "Find the full path to a file named by fileName.  Paths "
+      "are searched in the order specified.  A cache entry named by "
+      "<VAR> is created to store the result.  If the file is not "
+      "found, the result will be <VAR>-NOTFOUND.  If DOC is specified "
+      "then the next argument is treated as a documentation string for "
+      "the cache entry <VAR>.  Note that since executables can have "
+      "different extensions on different platforms, FIND_PROGRAM "
+      "should be used instead of FIND_FILE when looking for them.";
     }
   
   cmTypeMacro(cmFindFileCommand, cmCommand);

Source/cmFindLibraryCommand.h

@@ -69,16 +69,20 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  FIND_LIBRARY(VAR libraryName\n"
-      "               [NAMES name1 name2 ...]\n"
+      "  FIND_LIBRARY(<VAR> NAMES name1 [name2 ...]\n"
       "               [PATHS path1 path2 ...]\n"
-      "               [DOC helpstring])\n"
-      "Find the library by looking in paths specified in the command.  "
-      "A cache entry named by VAR is created to "
-      "store the result.  VAR-NOTFOUND is the value used if the library was "
-      "not found.  CMake will continue to look as long as the value "
-      "is not found.  If DOC is specified the next argument is the "
-      "documentation string for the cache entry VAR.";
+      "               [DOC \"docstring\"])\n"
+      "Find a library named by one of the names given after the NAMES "
+      "argument.  Paths specified after the PATHS argument are searched "
+      "in the order specified.  A cache entry named by <VAR> is created "
+      "to store the result.  If the library is not found, the result "
+      "will be <VAR>-NOTFOUND.  If DOC is specified then the next "
+      "argument is treated as a documentation string for the cache "
+      "entry <VAR>.\n"
+      "  FIND_LIBRARY(VAR libraryName [path1 path2 ...])\n"
+      "Find a library with the given name by searching in the specified "
+      "paths.  This is a short-hand signature for the command that is "
+      "sufficient in many cases.";
     }
   
   cmTypeMacro(cmFindLibraryCommand, cmCommand);

Source/cmFindPathCommand.h

@@ -69,13 +69,14 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  FIND_PATH(VAR fileName path1 path2 ... [DOC docstring])\n"
-      "If the file is found, then VAR is set to the path where it was found.  "
-      "A cache entry named by VAR is created to "
-      "store the result.  VAR-NOTFOUND is the value used if the file was "
-      "not found.  CMake will continue to look as long as the value "
-      "is not found.  If DOC is specified the next argument is the "
-      "documentation string for the cache entry VAR.";
+      "  FIND_PATH(<VAR> fileName path1 [path2 ...]\n"
+      "            [DOC \"docstring\"])\n"
+      "Find the directory containing a file named by fileName.  Paths "
+      "are searched in the order specified.  A cache entry named by "
+      "<VAR> is created to store the result.  If the file is not "
+      "found, the result will be <VAR>-NOTFOUND.  If DOC is specified "
+      "then the next argument is treated as a documentation string for "
+      "the cache entry <VAR>.\n";
     }
   
   cmTypeMacro(cmFindPathCommand, cmCommand);

Source/cmFindProgramCommand.h

@@ -69,19 +69,23 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  FIND_PROGRAM(VAR executableName\n"
-      "               [NAMES name1 name2 ...]\n"
+      "  FIND_PROGRAM(<VAR> NAMES name1 [name2 ...]\n"
       "               [PATHS path1 path2 ...]\n"
       "               [NO_SYSTEM_PATH]\n"
-      "               [DOC helpstring])\n"
-      "Find the executable in the system PATH or in any extra paths "
-      "specified in the command.  A cache entry named by VAR is created to "
-      "store the result.  VAR-NOTFOUND is the value used if the program was "
-      "not found.  CMake will continue to look as long as the value "
-      "is not found.  If DOC is specified the next argument is the "
-      "documentation string for the cache entry VAR.  "
-      "If NO_SYSTEM_PATH is specified the contents of system PATH are not "
-      "used.";
+      "               [DOC \"docstring\"])\n"
+      "Find an executable named by one of the names given after the NAMES "
+      "argument.  Paths specified after the PATHS argument are searched "
+      "in the order specified.  If the NO_SYSTEM_PATH argument is not "
+      "specified, the search continues with the system search path "
+      "specified by the PATH environment variable.  A cache entry named "
+      "by <VAR> is created to store the result.  If the program is not "
+      "found, the result will be <VAR>-NOTFOUND.  If DOC is specified "
+      "then the next argument is treated as a documentation string for "
+      "the cache entry <VAR>.\n"
+      "  FIND_PROGRAM(VAR executableName [path1 path2 ...])\n"
+      "Find a program with the given name by searching in the specified "
+      "paths.  This is a short-hand signature for the command that is "
+      "sufficient in many cases.";
     }
   
   cmTypeMacro(cmFindProgramCommand, cmCommand);