ENH: add ability to get documentaiton of a property from a script

Source/cmGetPropertyCommand.cxx

@@ -18,6 +18,7 @@
 
 #include "cmake.h"
 #include "cmTest.h"
+#include "cmPropertyDefinition.h"
 
 // cmGetPropertyCommand
 bool cmGetPropertyCommand::InitialPass(
@@ -31,33 +32,51 @@ bool cmGetPropertyCommand::InitialPass(
 
   // the last argument in the property to get
   const char *property = args[args.size()-1].c_str();
+  bool get_brief = false;
+  if (!strcmp(property,"BRIEF_DOCS"))
+    {
+    get_brief = true;
+    property = args[args.size()-2].c_str();
+    }
+  bool get_full = false;
+  if (!strcmp(property,"FULL_DOCS"))
+    {
+    get_full = true;
+    property = args[args.size()-2].c_str();
+    }
+
   std::string output = "NOTFOUND";
 
   cmProperty::ScopeType scope;
   const char *scopeName = 0;
-  if (args[1] == "GLOBAL" && args.size() == 3)
+  if (args[1] == "GLOBAL")
     {
     scope = cmProperty::GLOBAL;
     }
+  else if (args[1] == "VARIABLE")
+    {
+    scope = cmProperty::VARIABLE;
+    }
   else if (args[1] == "DIRECTORY" && args.size() >= 3)
     {
     scope = cmProperty::DIRECTORY;
-    if (args.size() >= 4)
+    if ((args.size() == 4 && !get_brief && !get_full) ||
+        (args.size() == 5 && (get_brief || get_full)))
       {
       scopeName = args[2].c_str();
       }
     }
-  else if (args[1] == "TARGET" && args.size() == 4)
+  else if (args[1] == "TARGET" && args.size() >= 4)
     {
     scope = cmProperty::TARGET;
     scopeName = args[2].c_str();
     }
-  else if (args[1] == "TEST" && args.size() == 4)
+  else if (args[1] == "TEST" && args.size() >= 4)
     {
     scope = cmProperty::TEST;
     scopeName = args[2].c_str();
     }
-  else if (args[1] == "SOURCE_FILE" && args.size() == 4)
+  else if (args[1] == "SOURCE_FILE" && args.size() >= 4)
     {
     scope = cmProperty::SOURCE_FILE;
     scopeName = args[2].c_str();
@@ -68,8 +87,37 @@ bool cmGetPropertyCommand::InitialPass(
     return false;
     }
   
-  switch (scope) 
+  if (get_brief)
+    {
+    cmPropertyDefinition *def = 
+      this->Makefile->GetCMakeInstance()->
+      GetPropertyDefinition(property,scope);
+    if (def)
+      {
+      output = def->GetShortDescription();
+      }
+    }
+  else if (get_full)
+    {
+    cmPropertyDefinition *def = 
+      this->Makefile->GetCMakeInstance()->
+      GetPropertyDefinition(property,scope);
+    if (def)
+      {
+      output = def->GetFullDescription();
+      }
+    }
+  
+  else switch (scope) 
+    {
+    case cmProperty::VARIABLE:
+      {
+      if (this->Makefile->GetDefinition(property))
         {
+        output = this->Makefile->GetDefinition(property);
+        }
+      }
+      break;
     case cmProperty::TARGET:
       {
       cmTarget *tgt = this->Makefile->GetLocalGenerator()->GetGlobalGenerator()
@@ -152,7 +200,6 @@ bool cmGetPropertyCommand::InitialPass(
         }
       }
       break;
-    case cmProperty::VARIABLE:
     case cmProperty::CACHED_VARIABLE:
       // not handled by GetProperty
       break;

Source/cmGetPropertyCommand.h

@@ -58,11 +58,17 @@ public:
     {
       return
         "  get_property(VAR scope_value property)\n"
+        "  get_property(VAR scope_value property \n"
+        "               BRIEF_DOCS)\n"
+        "  get_property(VAR scope_value property \n"
+        "               FULL_DOCS)\n"
         "Get a property from cmake.  The scope_value is either GLOBAL, "
         "DIRECTORY dir_name, TARGET tgt_name, SOURCE_FILE src_name, "
-        "or TEST test_name. The resulting value is "
+        "TEST test_name or VARIABLE var_name. The resulting value is "
         "stored in the variable VAR. If the property is not found, "
-        "CMake will report an error.";
+        "CMake will report an error. The second and third signatures "
+        "return the documentation for a property or variable instead of "
+        "its value.";
     }
   
   cmTypeMacro(cmGetPropertyCommand, cmCommand);

Source/cmPropertyDefinition.h

@@ -46,6 +46,12 @@ public:
   cmProperty::ScopeType GetScope() const {
     return this->Scope; };
 
+  // get the docs
+  const std::string &GetShortDescription() const {
+    return this->ShortDescription; }; 
+  const std::string &GetFullDescription() const {
+    return this->FullDescription; }; 
+  
 protected:
   std::string Name;
   std::string ShortDescription;

Source/cmake.cxx

@@ -3093,6 +3093,17 @@ void cmake::DefineProperty(const char *name, cmProperty::ScopeType scope,
                                                   chained);
 }
 
+cmPropertyDefinition *cmake
+::GetPropertyDefinition(const char *name, 
+                        cmProperty::ScopeType scope)
+{
+  if (this->IsPropertyDefined(name,scope))
+    {
+    return &(this->PropertyDefinitions[scope][name]);
+    }
+  return 0;
+}
+
 bool cmake::IsPropertyDefined(const char *name, cmProperty::ScopeType scope)
 {
   return this->PropertyDefinitions[scope].IsPropertyDefined(name);

Source/cmake.h

@@ -312,6 +312,10 @@ class cmake
                       bool chain = false, 
                       const char *variableGroup = 0);
 
+  // get property definition
+  cmPropertyDefinition *GetPropertyDefinition
+  (const char *name, cmProperty::ScopeType scope);
+
   // Is a property defined?
   bool IsPropertyDefined(const char *name, cmProperty::ScopeType scope);
   bool IsPropertyChained(const char *name, cmProperty::ScopeType scope);