ENH: add --help-policies and --help-policy command line options

Source/cmDocumentation.cxx

@@ -338,6 +338,8 @@ bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
       return this->PrintDocumentationSingle(os);
     case cmDocumentation::SingleModule:
       return this->PrintDocumentationSingleModule(os);
+    case cmDocumentation::SinglePolicy:
+      return this->PrintDocumentationSinglePolicy(os);
     case cmDocumentation::SingleProperty:
       return this->PrintDocumentationSingleProperty(os);
     case cmDocumentation::SingleVariable:
@@ -381,6 +383,8 @@ bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
       return this->PrintDocumentationModules(os);
     case cmDocumentation::CustomModules: 
       return this->PrintDocumentationCustomModules(os);
+    case cmDocumentation::Policies: 
+      return this->PrintDocumentationPolicies(os);
     case cmDocumentation::Properties: 
       return this->PrintDocumentationProperties(os);
     case cmDocumentation::Variables: 
@@ -694,6 +698,12 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv)
       GET_OPT_ARGUMENT(help.Filename);
       help.HelpForm = this->GetFormFromFilename(help.Filename);
       }
+    else if(strcmp(argv[i], "--help-policies") == 0)
+      {
+      help.HelpType = cmDocumentation::Policies;
+      GET_OPT_ARGUMENT(help.Filename);
+      help.HelpForm = this->GetFormFromFilename(help.Filename);
+      }
     else if(strcmp(argv[i], "--help-variables") == 0)
       {
       help.HelpType = cmDocumentation::Variables;
@@ -764,6 +774,13 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv)
       GET_OPT_ARGUMENT(help.Filename);
       help.HelpForm = this->GetFormFromFilename(help.Filename);
       }
+    else if(strcmp(argv[i], "--help-policy") == 0)
+      {
+      help.HelpType = cmDocumentation::SinglePolicy;
+      GET_OPT_ARGUMENT(help.Argument);
+      GET_OPT_ARGUMENT(help.Filename);
+      help.HelpForm = this->GetFormFromFilename(help.Filename);
+      }
     else if(strcmp(argv[i], "--help-variable") == 0)
       {
       help.HelpType = cmDocumentation::SingleVariable;
@@ -1132,6 +1149,20 @@ bool cmDocumentation::PrintDocumentationSingleProperty(std::ostream& os)
   return false;
 }
 
+//----------------------------------------------------------------------------
+bool cmDocumentation::PrintDocumentationSinglePolicy(std::ostream& os)
+{
+  if (this->PrintDocumentationGeneric(os,"Policies"))
+    {
+    return true;
+    }
+
+  // Argument was not a command.  Complain.
+  os << "Argument \"" << this->CurrentArgument.c_str()
+     << "\" to --help-policy is not a CMake policy.\n";
+  return false;
+}
+
 //----------------------------------------------------------------------------
 bool cmDocumentation::PrintDocumentationSingleVariable(std::ostream& os)
 {
@@ -1232,6 +1263,21 @@ bool cmDocumentation::PrintDocumentationCustomModules(std::ostream& os)
   return true;
 }
 
+//----------------------------------------------------------------------------
+bool cmDocumentation::PrintDocumentationPolicies(std::ostream& os)
+{
+  this->ClearSections();
+  this->AddSectionToPrint("Description");
+  this->AddSectionToPrint("Policies");
+  this->AddSectionToPrint("Copyright");
+  this->AddSectionToPrint("See Also");
+
+  this->CurrentFormatter->PrintHeader(this->GetNameString(), os);
+  this->Print(os);
+  this->CurrentFormatter->PrintFooter(os);
+  return true;
+}
+
 //----------------------------------------------------------------------------
 bool cmDocumentation::PrintDocumentationProperties(std::ostream& os)
 {

Source/cmDocumentation.h

@@ -138,11 +138,13 @@ private:
   bool PrintDocumentationSingle(std::ostream& os);
   bool PrintDocumentationSingleModule(std::ostream& os);
   bool PrintDocumentationSingleProperty(std::ostream& os);
+  bool PrintDocumentationSinglePolicy(std::ostream& os);
   bool PrintDocumentationSingleVariable(std::ostream& os);
   bool PrintDocumentationUsage(std::ostream& os);
   bool PrintDocumentationFull(std::ostream& os);
   bool PrintDocumentationModules(std::ostream& os);
   bool PrintDocumentationCustomModules(std::ostream& os);
+  bool PrintDocumentationPolicies(std::ostream& os);
   bool PrintDocumentationProperties(std::ostream& os);
   bool PrintDocumentationVariables(std::ostream& os);
   bool PrintDocumentationCurrentCommands(std::ostream& os);

Source/cmDocumentationFormatter.h

@@ -33,7 +33,7 @@ public:
   { None, Usage, Single, SingleModule, SingleProperty, SingleVariable,
     List, ModuleList, PropertyList, VariableList,
     Full, Properties, Variables, Modules, CustomModules, Commands, 
-    CompatCommands, Copyright, Version };
+    CompatCommands, Copyright, Version, Policies, SinglePolicy };
 
   /** Forms of documentation output.  */
   enum Form { TextForm, HTMLForm, ManForm, UsageForm, DocbookForm };

Source/cmPolicies.cxx

@@ -409,3 +409,23 @@ cmPolicies::GetPolicyStatus(cmPolicies::PolicyID id)
   return pos->second->Status;
 }
 
+void cmPolicies::GetDocumentation(std::vector<cmDocumentationEntry>& v)
+{
+  // now loop over all the policies and set them as appropriate
+  std::map<cmPolicies::PolicyID,cmPolicy *>::iterator i 
+    = this->Policies.begin();
+  for (;i != this->Policies.end(); ++i)
+  {
+    std::string full;
+    full += i->second->LongDescription;
+    // add in some more text here based on status
+    // switch (i->second->Status)
+    // {
+      // case cmPolicies::WARN:
+          
+    cmDocumentationEntry e(i->second->IDString.c_str(),
+                           i->second->ShortDescription.c_str(),
+                           full.c_str());
+    v.push_back(e);
+  }
+}

Source/cmPolicies.h

@@ -77,6 +77,9 @@ public:
   ///! return an error string for when a required policy is unspecified
   std::string GetRequiredPolicyError(cmPolicies::PolicyID id);
 
+  ///! Get docs for policies
+  void GetDocumentation(std::vector<cmDocumentationEntry>& v);
+
   private:
   // might have to make these internal for VS6 not sure yet
   std::map<PolicyID,cmPolicy *> Policies;

Source/cmake.cxx

@@ -2444,6 +2444,11 @@ void cmake::GetCommandDocumentation(std::vector<cmDocumentationEntry>& v,
     }
 }
 
+void cmake::GetPolicyDocumentation(std::vector<cmDocumentationEntry>& v)
+{
+  this->Policies->GetDocumentation(v);
+}
+
 void cmake::GetPropertiesDocumentation(std::map<std::string,
                                        cmDocumentationSection *>& v)
 {

Source/cmake.h

@@ -258,6 +258,7 @@ class cmake
   void GetPropertiesDocumentation(std::map<std::string,
                                   cmDocumentationSection *>&);
   void GetGeneratorDocumentation(std::vector<cmDocumentationEntry>&);
+  void GetPolicyDocumentation(std::vector<cmDocumentationEntry>& entries);
 
   ///! Set/Get a property of this target file
   void SetProperty(const char *prop, const char *value);

Source/cmakemain.cxx

@@ -324,10 +324,12 @@ int do_cmake(int ac, char** av)
       }
 
     std::vector<cmDocumentationEntry> commands;
+    std::vector<cmDocumentationEntry> policies;
     std::vector<cmDocumentationEntry> compatCommands;
     std::vector<cmDocumentationEntry> generators;
     std::map<std::string,cmDocumentationSection *> propDocs;
 
+    hcm.GetPolicyDocumentation(policies);
     hcm.GetCommandDocumentation(commands, true, false);
     hcm.GetCommandDocumentation(compatCommands, false, true);
     hcm.GetPropertiesDocumentation(propDocs);
@@ -340,6 +342,7 @@ int do_cmake(int ac, char** av)
     doc.AppendSection("Generators",generators);
     doc.PrependSection("Options",cmDocumentationOptions);
     doc.SetSection("Commands",commands);
+    doc.SetSection("Policies",policies);
     doc.AppendSection("Compatibility Commands",compatCommands);
     doc.SetSections(propDocs);