ENH: add possibility to add doc strings to varibles created by find type commands

Source/cmFindFileCommand.cxx

@@ -45,22 +45,38 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   
 
 // cmFindFileCommand
-bool cmFindFileCommand::InitialPass(std::vector<std::string> const& args)
+bool cmFindFileCommand::InitialPass(std::vector<std::string> const& argsIn)
 {
-  if(args.size() < 2)
+  if(argsIn.size() < 2)
     {
     this->SetError("called with incorrect number of arguments");
     return false;
     }
-
+  std::string helpString = "Where can the ";
+  helpString += argsIn[1] + " file be found";
+  unsigned int size = argsIn.size();
+  std::vector<std::string> args;
+  for(unsigned int j = 0; j < size; ++j)
+    {
+    if(argsIn[j] != "DOC")
+      {
+      args.push_back(argsIn[j]);
+      }
+    else
+      {
+      if(j+1 < size)
+        {
+        helpString = argsIn[j+1];
+        }
+      break;
+      }
+    }
   std::vector<std::string>::const_iterator i = args.begin();
   // Use the first argument as the name of something to be defined
   const char* define = (*i).c_str();
   i++; // move iterator to next arg
   // Now check and see if the value has been stored in the cache
   // already, if so use that value and don't look for the program
-  std::string helpString = "Where can the ";
-  helpString += args[1] + " file be found";
   const char* cacheValue
     = m_Makefile->GetDefinition(define);
   if(cacheValue && strcmp(cacheValue, "NOTFOUND"))

Source/cmFindFileCommand.h

@@ -94,7 +94,11 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "FIND_FILE(NAME file extrapath extrapath ...)";
+      "FIND_FILE(NAME file extrapath extrapath ... [DOC docstring])"
+      "Find a file in the system PATH or in any extra paths specified in the command."
+      "A cache entry called NAME is created to store the result.   NOTFOUND is the value"
+      " used if the file was not found.  If DOC is specified the next argument is the "
+      "documentation string for the cache entry NAME.";
     }
   
   cmTypeMacro(cmFindFileCommand, cmCommand);

Source/cmFindLibraryCommand.cxx

@@ -44,11 +44,28 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 // cmFindLibraryCommand
 bool cmFindLibraryCommand::InitialPass(std::vector<std::string> const& argsIn)
 {
-  std::vector<std::string>  args = argsIn;
-  if(args.size() < 2)
+  if(argsIn.size() < 2)
     {
     this->SetError("called with incorrect number of arguments");
     return false;
+    } 
+  std::string helpString;
+  unsigned int size = argsIn.size();
+  std::vector<std::string> args;
+  for(unsigned int j = 0; j < size; ++j)
+    {
+    if(argsIn[j] != "DOC")
+      {
+      args.push_back(argsIn[j]);
+      }
+    else
+      {
+      if(j+1 < size)
+        {
+        helpString = argsIn[j+1];
+        }
+      break;
+      }
     }
 
   std::vector<std::string> path;
@@ -101,26 +118,28 @@ bool cmFindLibraryCommand::InitialPass(std::vector<std::string> const& argsIn)
       cmSystemTools::GlobDirs(exp.c_str(), path);
       }
     }
-
-  std::string helpString = "Where can ";
-  if (names.size() == 0)
-    {
-    helpString += "the (unknown) library be found";
-    }
-  else if (names.size() == 1)
+  if(helpString.size() == 0)
     {
-    helpString += "the " + names[0] + " library be found";
-    }
-  else
-    {
-    helpString += "one of the " + names[0];
-    for (unsigned int j = 1; j < names.size() - 1; ++j)
+    helpString = "Where can ";
+    if (names.size() == 0)
+      {
+      helpString += "the (unknown) library be found";
+      }
+    else if (names.size() == 1)
+      {
+      helpString += "the " + names[0] + " library be found";
+      }
+    else
       {
-      helpString += ", " + names[j];
+      helpString += "one of the " + names[0];
+      for (unsigned int j = 1; j < names.size() - 1; ++j)
+        {
+        helpString += ", " + names[j];
+        }
+      helpString += " or " + names[names.size() - 1] + " libraries be found";
       }
-    helpString += " or " + names[names.size() - 1] + " libraries be found";
     }
-
+  
   const char* cacheValue
     = m_Makefile->GetDefinition(args[0].c_str());
   if(cacheValue && strcmp(cacheValue, "NOTFOUND"))

Source/cmFindLibraryCommand.h

@@ -94,8 +94,10 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "FIND_LIBRARY(DEFINE_PATH libraryName [NAMES] name1 name2 name3 [PATHS path1 path2 path3...])\n"
-      "If the library is found, then DEFINE_PATH is set to the full path where it was found";
+      "FIND_LIBRARY(DEFINE_PATH libraryName [NAMES] name1 name2 name3 [PATHS path1 path2 path3...] [DOC docstring] )\n"
+      "If the library is found, then DEFINE_PATH is set to the full path where it was found.  "
+      "If DOC is specified the next argument is the "
+      "documentation string for the cache entry NAME.";
     }
   
   cmTypeMacro(cmFindLibraryCommand, cmCommand);

Source/cmFindPathCommand.cxx

@@ -42,9 +42,9 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include "cmCacheManager.h"
 
 // cmFindPathCommand
-bool cmFindPathCommand::InitialPass(std::vector<std::string> const& args)
+bool cmFindPathCommand::InitialPass(std::vector<std::string> const& argsIn)
 {
-  if(args.size() < 2)
+  if(argsIn.size() < 2)
     {
     this->SetError("called with incorrect number of arguments");
     return false;
@@ -53,7 +53,24 @@ bool cmFindPathCommand::InitialPass(std::vector<std::string> const& args)
   // Now check and see if the value has been stored in the cache
   // already, if so use that value and don't look for the program
   std::string helpString = "What is the path where the file ";
-  helpString += args[1] + " can be found";
+  helpString += argsIn[1] + " can be found";
+  std::vector<std::string> args;
+  unsigned int size = argsIn.size();
+  for(unsigned int j = 0; j < size; ++j)
+    {
+    if(argsIn[j] != "DOC")
+      {
+      args.push_back(argsIn[j]);
+      }
+    else
+      {
+      if(j+1 < size)
+        {
+        helpString = argsIn[j+1];
+        }
+      break;
+      }
+    }
   const char* cacheValue
     = m_Makefile->GetDefinition(args[0].c_str());
   if(cacheValue && strcmp(cacheValue, "NOTFOUND"))

Source/cmFindPathCommand.h

@@ -70,7 +70,9 @@ public:
     {
     return
       "FIND_PATH(PATH_DEFINE fileName path1 path2 path3...)\n"
-      "If the file is found, then PATH_DEFINE is set to the path where it was found";
+      "If the file is found, then PATH_DEFINE is set to the path where it was found."
+      "If DOC is specified the next argument is the "
+      "documentation string for the cache entry NAME.";
     }
   
   cmTypeMacro(cmFindPathCommand, cmCommand);

Source/cmFindProgramCommand.cxx

@@ -52,7 +52,24 @@ bool cmFindProgramCommand::InitialPass(std::vector<std::string> const& argsIn)
     this->SetError("called with incorrect number of arguments");
     return false;
     }
-  std::vector<std::string> args = argsIn;
+  std::string doc = "Path to a program.";
+  unsigned int size = argsIn.size();
+  std::vector<std::string> args;
+  for(unsigned int j = 0; j < size; ++j)
+    {
+    if(argsIn[j] != "DOC")
+      {
+      args.push_back(argsIn[j]);
+      }
+    else
+      {
+      if(j+1 < size)
+        {
+        doc = argsIn[j+1];
+        }
+      break;
+      }
+    }
   std::vector<std::string>::iterator i = args.begin();
   // Use the first argument as the name of something to be defined
   const char* define = (*i).c_str();
@@ -125,7 +142,7 @@ bool cmFindProgramCommand::InitialPass(std::vector<std::string> const& argsIn)
       // Save the value in the cache
       m_Makefile->AddCacheDefinition(define,
                                      result.c_str(),
-                                     "Path to a program.",
+                                     doc.c_str(),
                                      cmCacheManager::FILEPATH);
       
       return true;
@@ -133,7 +150,7 @@ bool cmFindProgramCommand::InitialPass(std::vector<std::string> const& argsIn)
     }
   m_Makefile->AddCacheDefinition(args[0].c_str(),
                                  "NOTFOUND",
-                                 "Path to a program",
+                                 doc.c_str(),
                                  cmCacheManager::FILEPATH);
   return true;
 }

Source/cmFindProgramCommand.h

@@ -94,7 +94,11 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "FIND_PROGRAM(NAME executable1 extrapath extrapath ...)";
+      "FIND_PROGRAM(NAME executable1 extrapath extrapath ... [DOC helpstring]) "
+      "Find the executable in the system PATH or in any extra paths specified in the command."
+      "A cache entry called NAME is created to store the result.   NOTFOUND is the value"
+      " used if the program was not found.  If DOC is specified the next argument is the "
+      "documentation string for the cache entry NAME.";
     }
   
   cmTypeMacro(cmFindProgramCommand, cmCommand);