STYLE: sort the property documentation into

global/directory/target/test/sourcefile and variable sections

Alex

Source/cmDocumentation.cxx

@@ -64,7 +64,8 @@ static const cmDocumentationEntry cmModulesDocumentationDescription[] =
 static const cmDocumentationEntry cmPropertiesDocumentationDescription[] =
 {
   {0,
-   "  CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.", 0},
+   "  CMake Properties - Properties supported by CMake, "
+   "the Cross-Platform Makefile Generator.", 0},
 //  CMAKE_DOCUMENTATION_OVERVIEW,
   {0,
    "This is the documentation for the properties supported by CMake. "
@@ -79,7 +80,8 @@ static const cmDocumentationEntry cmPropertiesDocumentationDescription[] =
 static const cmDocumentationEntry cmCompatCommandsDocumentationDescription[] =
 {
   {0,
-   "  CMake Compatibility Listfile Commands - Obsolete commands supported by CMake for compatibility.", 0},
+   "  CMake Compatibility Listfile Commands - "
+   "Obsolete commands supported by CMake for compatibility.", 0},
 //  CMAKE_DOCUMENTATION_OVERVIEW,
   {0,
   "This is the documentation for now obsolete listfile commands from "
@@ -97,10 +99,60 @@ static const cmDocumentationEntry cmDocumentationCommandsHeader[] =
 };
 
 //----------------------------------------------------------------------------
-static const cmDocumentationEntry cmDocumentationPropertiesHeader[] =
+static const cmDocumentationEntry cmDocumentationGlobalPropertiesHeader[] =
 {
   {0,
-   "The following properties are available in CMakeLists.txt code:", 0},
+   "The following global properties are available in CMakeLists.txt code:", 0},
+  {0,0,0}
+};
+
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmDocumentationDirectoryPropertiesHeader[] =
+{
+  {0
+   ,"The following directory properties are available in CMakeLists.txt code:"
+   ,0},
+  {0,0,0}
+};
+
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmDocumentationTargetPropertiesHeader[] =
+{
+  {0,
+   "The following target properties are available in CMakeLists.txt code:", 0},
+  {0,0,0}
+};
+
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmDocumentationTestPropertiesHeader[] =
+{
+  {0
+   ,"The following properties for tests are available in CMakeLists.txt code:"
+   ,0},
+  {0,0,0}
+};
+
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmDocumentationSourceFilePropertiesHeader[] =
+{
+  {0
+  ,"The following source file properties are available in CMakeLists.txt code:"
+  , 0},
+  {0,0,0}
+};
+
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmDocumentationVariablePropertiesHeader[] =
+{
+  {0, "The following variables are available in CMakeLists.txt code:", 0},
+  {0,0,0}
+};
+
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry 
+                             cmDocumentationCachedVariablePropertiesHeader[] =
+{
+  {0,"The following cache variables are available in CMakeLists.txt code:", 0},
   {0,0,0}
 };
 
@@ -211,15 +263,35 @@ cmDocumentation::cmDocumentation()
 ,CompatCommandsSection("Compatibility Listfile Commands",
                        "COMPATIBILITY COMMANDS")
 ,ModulesSection       ("Standard CMake Modules",          "MODULES")
-,PropertiesSection    ("Standard Properties",             "PROPERTIES")
 ,GeneratorsSection    ("Generators",                      "GENERATORS")
 ,SeeAlsoSection       ("See Also",                        "SEE ALSO")
 ,CopyrightSection     ("Copyright",                       "COPYRIGHT")
 ,AuthorSection        ("Author",                          "AUTHOR")
+,GlobalPropertiesSection        ("Standard Properties",   "GLOBAL PROPERTIES")
+,DirectoryPropertiesSection     ("Directory Properties",  
+                                 "DIRECTORY PROPERTIES")
+,TargetPropertiesSection        ("Target Properties",     "TARGET PROPERTIES")
+,TestPropertiesSection          ("Test Properties",       "TEST PROPERTIES")
+,SourceFilePropertiesSection    ("Sourcefile Properties", 
+                                 "SOURCEFILE PROPERTIES")
+,VariablePropertiesSection      ("Variables",             "VARIABLES")
+,CachedVariablePropertiesSection("Cached Variables",      "CACHE VARIABLES")
 {
   this->CurrentForm = TextForm;
   this->TextIndent = "";
   this->TextWidth = 77;
+  
+  this->PropertySections[cmProperty::GLOBAL] = &this->GlobalPropertiesSection;
+  this->PropertySections[cmProperty::DIRECTORY] = 
+                                             &this->DirectoryPropertiesSection;
+  this->PropertySections[cmProperty::TARGET] = &this->TargetPropertiesSection;
+  this->PropertySections[cmProperty::TEST] = &this->TestPropertiesSection;
+  this->PropertySections[cmProperty::SOURCE_FILE] = 
+                                            &this->SourceFilePropertiesSection;
+  this->PropertySections[cmProperty::VARIABLE] = 
+                                              &this->VariablePropertiesSection;
+  this->PropertySections[cmProperty::CACHED_VARIABLE] = 
+                                        &this->CachedVariablePropertiesSection;
 }
 
 //----------------------------------------------------------------------------
@@ -730,9 +802,42 @@ void cmDocumentation::SetCompatCommandsSection(const cmDocumentationEntry*
 
 //----------------------------------------------------------------------------
 void cmDocumentation
-::SetPropertiesSection(const cmDocumentationEntry* section)
+::SetPropertiesSection(const cmDocumentationEntry* section, 
+                       cmProperty::ScopeType type)
 {
-  this->PropertiesSection.Set(cmDocumentationPropertiesHeader, section, 0);
+  switch(type)
+  {
+  case cmProperty::GLOBAL:
+    this->GlobalPropertiesSection.Set(
+                            cmDocumentationGlobalPropertiesHeader, section, 0);
+    break;
+  case cmProperty::DIRECTORY:
+    this->DirectoryPropertiesSection.Set(
+                          cmDocumentationDirectoryPropertiesHeader, section, 0);
+    break;
+  case cmProperty::TARGET:
+    this->TargetPropertiesSection.Set(
+                            cmDocumentationTargetPropertiesHeader, section, 0);
+    break;
+  case cmProperty::TEST:
+    this->TestPropertiesSection.Set(
+                              cmDocumentationTestPropertiesHeader, section, 0);
+    break;
+  case cmProperty::SOURCE_FILE:
+    this->SourceFilePropertiesSection.Set(
+                        cmDocumentationSourceFilePropertiesHeader, section, 0);
+    break;
+  case cmProperty::VARIABLE:
+    this->VariablePropertiesSection.Set(
+                        cmDocumentationVariablePropertiesHeader, section, 0);
+    break;
+  case cmProperty::CACHED_VARIABLE:
+    this->CachedVariablePropertiesSection.Set(
+                    cmDocumentationCachedVariablePropertiesHeader, section, 0);
+    break;
+  default:
+    break;
+  }
 }
 
 //----------------------------------------------------------------------------
@@ -1312,7 +1417,7 @@ bool cmDocumentation::PrintDocumentationSingleModule(std::ostream& os)
 //----------------------------------------------------------------------------
 bool cmDocumentation::PrintDocumentationSingleProperty(std::ostream& os)
 {
-  if(this->PropertiesSection.IsEmpty())
+  if(this->GlobalPropertiesSection.IsEmpty())
     {
     os << "Internal error: properties list is empty." << std::endl;
     return false;
@@ -1322,13 +1427,20 @@ bool cmDocumentation::PrintDocumentationSingleProperty(std::ostream& os)
     os << "Argument --help-property needs a property name.\n";
     return false;
     }
-  for(const cmDocumentationEntry* entry = this->PropertiesSection.GetEntries();
+
-      entry->brief; ++entry)
+  for(std::map<cmProperty::ScopeType, cmSection*>::const_iterator 
+      sectionIt = this->PropertySections.begin();
+      sectionIt != this->PropertySections.end();
+      ++sectionIt)
     {
-    if(entry->name && this->CurrentArgument == entry->name)
+    for(const cmDocumentationEntry* 
+        entry = sectionIt->second->GetEntries(); entry->brief; ++entry)
       {
-      this->PrintDocumentationCommand(os, entry);
+      if(entry->name && this->CurrentArgument == entry->name)
-      return true;
+        {
+        this->PrintDocumentationCommand(os, entry);
+        return true;
+        }
       }
     }
   // Argument was not a command.  Complain.
@@ -1371,19 +1483,37 @@ bool cmDocumentation::PrintDocumentationList(std::ostream& os)
 //----------------------------------------------------------------------------
 bool cmDocumentation::PrintPropertyList(std::ostream& os)
 {
-  if(this->PropertiesSection.IsEmpty())
+  if(this->GlobalPropertiesSection.IsEmpty())
     {
     os << "Internal error: properties list is empty." << std::endl;
     return false;
     }
-  for(const cmDocumentationEntry* entry = this->PropertiesSection.GetEntries();
+  for(const cmDocumentationEntry* 
-      entry->brief; ++entry)
+      entry = this->GlobalPropertiesSection.GetEntries();
+      entry->brief; 
+      ++entry)
     {
     if(entry->name)
       {
       os << entry->name << std::endl;
       }
     }
+
+  for(std::map<cmProperty::ScopeType, cmSection*>::const_iterator 
+      sectionIt = this->PropertySections.begin();
+      sectionIt != this->PropertySections.end();
+      ++sectionIt)
+    {
+    for(const cmDocumentationEntry* 
+        entry = sectionIt->second->GetEntries(); entry->brief; ++entry)
+      {
+      if(entry->name)
+        {
+        os << entry->name << std::endl;
+        }
+      }
+    }
+
   return true;
 }
 
@@ -1537,7 +1667,14 @@ void cmDocumentation::CreateFullDocumentation()
   this->AddSection(this->CommandsSection);
   this->AddSection(this->CompatCommandsSection);
   this->AddSection(this->ModulesSection);
-  this->AddSection(this->PropertiesSection);
+  this->AddSection(this->GlobalPropertiesSection);
+  this->AddSection(this->DirectoryPropertiesSection);
+  this->AddSection(this->TargetPropertiesSection);
+  this->AddSection(this->TestPropertiesSection);
+  this->AddSection(this->SourceFilePropertiesSection);
+  this->AddSection(this->VariablePropertiesSection);
+  this->AddSection(this->CachedVariablePropertiesSection);
+  
   this->AddSection(this->CopyrightSection.GetName(this->CurrentForm),
                    cmDocumentationCopyright);
 
@@ -1596,7 +1733,13 @@ void cmDocumentation::CreatePropertiesDocumentation()
   this->ClearSections();
   this->AddSection(this->DescriptionSection.GetName(CurrentForm), 
                    cmPropertiesDocumentationDescription);
-  this->AddSection(this->PropertiesSection);
+  this->AddSection(this->GlobalPropertiesSection);
+  this->AddSection(this->DirectoryPropertiesSection);
+  this->AddSection(this->TargetPropertiesSection);
+  this->AddSection(this->TestPropertiesSection);
+  this->AddSection(this->SourceFilePropertiesSection);
+  this->AddSection(this->VariablePropertiesSection);
+  this->AddSection(this->CachedVariablePropertiesSection);
   this->AddSection(this->CopyrightSection.GetName(CurrentForm), 
                    cmDocumentationCopyright);
   this->AddSection(this->SeeAlsoSection.GetName(CurrentForm), 

Source/cmDocumentation.h

@@ -18,6 +18,7 @@
 #define _cmDocumentation_h
 
 #include "cmStandardIncludes.h"
+#include "cmProperty.h"
 
 /** This is just a helper class to make it build with MSVC 6.0.
 Actually the enums and internal classes could directly go into
@@ -83,22 +84,23 @@ public:
 
   /** Set the program options for standard document generation.  */
   void SetOptionsSection(const cmDocumentationEntry*);
-  
+
   /** Set the listfile commands for standard document generation.  */
   void SetCommandsSection(const cmDocumentationEntry*);
-  
+
   /** Set the listfile compat. commands for standard document generation.  */
   void SetCompatCommandsSection(const cmDocumentationEntry*);
-  
+
-  /** Set the properties for standard document generation.  */
+  /** Set the global properties for standard document generation.  */
-  void SetPropertiesSection(const cmDocumentationEntry*);
+  void SetPropertiesSection(const cmDocumentationEntry*, 
+                            cmProperty::ScopeType type);
 
   /** Set the generator descriptions for standard document generation.  */
   void SetGeneratorsSection(const cmDocumentationEntry*);
-  
+
   /** Set the see-also list of references to the other tools.  */
   void SetSeeAlsoList(const cmDocumentationEntry*);
-  
+
   // Low-level interface for custom documents:
   /** Internal class representing a section of the documentation.
    * Cares e.g. for the different section titles in the different
@@ -244,12 +246,19 @@ private:
   cmSection CommandsSection;
   cmSection CompatCommandsSection;
   cmSection ModulesSection;
-  cmSection PropertiesSection;
   cmSection GeneratorsSection;
   cmSection SeeAlsoSection;
   cmSection CopyrightSection;
   cmSection AuthorSection;
-
+  cmSection GlobalPropertiesSection;
+  cmSection DirectoryPropertiesSection;
+  cmSection TargetPropertiesSection;
+  cmSection TestPropertiesSection;
+  cmSection SourceFilePropertiesSection;
+  cmSection VariablePropertiesSection;
+  cmSection CachedVariablePropertiesSection;
+  std::map<cmProperty::ScopeType, cmSection*> PropertySections;
+  
   std::string SeeAlsoString;
   std::string CMakeRoot;
   std::vector< char* > ModuleStrings;

Source/cmPropertyDefinition.cxx

@@ -20,7 +20,7 @@
 cmDocumentationEntry cmPropertyDefinition::GetDocumentation() const
 {
   cmDocumentationEntry e;
-  e.name = this->LongName.c_str();
+  e.name = this->Name.c_str();
   e.brief = 
     this->ShortDescription.size() ? this->ShortDescription.c_str() : 0;
   e.full = this->FullDescription.size() ? this->FullDescription.c_str() : 0;
@@ -44,24 +44,5 @@ void cmPropertyDefinition
     {
     this->FullDescription = fullDescription;
     }
-  this->LongName = this->Name;
-  switch (this->Scope)
-    {
-    case cmProperty::TARGET: this->LongName += " on a target";
-      break;
-    case cmProperty::SOURCE_FILE: this->LongName += " on a source file";
-      break;
-    case cmProperty::DIRECTORY: this->LongName += " on a directory";
-      break;
-    case cmProperty::GLOBAL: this->LongName += " globally";
-      break;
-    case cmProperty::TEST: this->LongName += " on CTest";
-      break;
-    case cmProperty::VARIABLE: this->LongName += " as a variable";
-      break;
-    case cmProperty::CACHED_VARIABLE: this->LongName += 
-                                        " as a cached variable";
-      break;
-    }
 }
 

Source/cmPropertyDefinition.h

@@ -39,7 +39,6 @@ public:
 
 protected:
   std::string Name;
-  std::string LongName;
   std::string ShortDescription;
   std::string FullDescription;
   cmProperty::ScopeType Scope; 

Source/cmake.cxx

@@ -2165,16 +2165,11 @@ void cmake::GetCommandDocumentation(std::vector<cmDocumentationEntry>& v,
   v.push_back(empty);
 }
 
-void cmake::GetPropertiesDocumentation(std::vector<cmDocumentationEntry>& v)
+void cmake::GetPropertiesDocumentation(std::vector<cmDocumentationEntry>& v, 
+                                       cmProperty::ScopeType type)
 {
   // get the properties for cmake
-  std::map<cmProperty::ScopeType, cmPropertyDefinitionMap>::iterator i = 
+  this->PropertyDefinitions[type].GetPropertiesDocumentation(v);
-    this->PropertyDefinitions.begin();
-  for (; i != this->PropertyDefinitions.end(); ++i)
-    {
-    i->second.GetPropertiesDocumentation(v);
-    }
-
   cmDocumentationEntry empty = {0,0,0};
   v.push_back(empty);
 }

Source/cmake.h

@@ -249,7 +249,8 @@ class cmake
   void GetCommandDocumentation(std::vector<cmDocumentationEntry>& entries, 
                                bool withCurrentCommands = true, 
                                bool withCompatCommands = true) const;
-  void GetPropertiesDocumentation(std::vector<cmDocumentationEntry>&);
+  void GetPropertiesDocumentation(std::vector<cmDocumentationEntry>&,
+                                  cmProperty::ScopeType type);
   void GetGeneratorDocumentation(std::vector<cmDocumentationEntry>&);
 
   ///! Set/Get a property of this target file

Source/cmakemain.cxx

@@ -95,32 +95,60 @@ static const cmDocumentationEntry cmDocumentationOptions[] =
    "Print extra stuff during the cmake run like stack traces with "
    "message(send_error ) calls."},
   {"--help-command cmd [file]", "Print help for a single command and exit.",
-   "Full documentation specific to the given command is displayed."},
+   "Full documentation specific to the given command is displayed. "
+   "If a file is specified, the documentation is written into and the output "
+   "format is determined depending on the filename suffix. Supported are man "
+   "page, HTML and plain text."},
   {"--help-command-list [file]", "List available listfile commands and exit.",
    "The list contains all commands for which help may be obtained by using "
-   "the --help-command argument followed by a command name.  If a file is "
+   "the --help-command argument followed by a command name. "
-   "specified, the help is written into it."},
+   "If a file is specified, the documentation is written into and the output "
+   "format is determined depending on the filename suffix. Supported are man "
+   "page, HTML and plain text."},
   {"--help-commands [file]", "Print help for all commands and exit.",
-   "Full documentation specific for all current command is displayed."},
+   "Full documentation specific for all current command is displayed."
+   "If a file is specified, the documentation is written into and the output "
+   "format is determined depending on the filename suffix. Supported are man "
+   "page, HTML and plain text."},
   {"--help-compatcommands [file]", "Print help for compatibility commands. ",
-   "Full documentation specific for all compatibility commands is displayed."},
+   "Full documentation specific for all compatibility commands is displayed."
+   "If a file is specified, the documentation is written into and the output "
+   "format is determined depending on the filename suffix. Supported are man "
+   "page, HTML and plain text."},
   {"--help-module module [file]", "Print help for a single module and exit.",
-   "Full documentation specific to the given module is displayed."},
+   "Full documentation specific to the given module is displayed."
+   "If a file is specified, the documentation is written into and the output "
+   "format is determined depending on the filename suffix. Supported are man "
+   "page, HTML and plain text."},
   {"--help-module-list [file]", "List available modules and exit.",
    "The list contains all modules for which help may be obtained by using "
-   "the --help-module argument followed by a module name.  If a file is "
+   "the --help-module argument followed by a module name. "
-   "specified, the help is written into it."},
+   "If a file is specified, the documentation is written into and the output "
+   "format is determined depending on the filename suffix. Supported are man "
+   "page, HTML and plain text."},
   {"--help-modules [file]", "Print help for all modules and exit.",
-   "Full documentation for all modules is displayed."},
+   "Full documentation for all modules is displayed. "
+   "If a file is specified, the documentation is written into and the output "
+   "format is determined depending on the filename suffix. Supported are man "
+   "page, HTML and plain text."},
   {"--help-property prop [file]", 
    "Print help for a single property and exit.",
-   "Full documentation specific to the given module is displayed."},
+   "Full documentation specific to the given module is displayed."
+   "If a file is specified, the documentation is written into and the output "
+   "format is determined depending on the filename suffix. Supported are man "
+   "page, HTML and plain text."},
   {"--help-property-list [file]", "List available properties and exit.",
    "The list contains all properties for which help may be obtained by using "
    "the --help-property argument followed by a property name.  If a file is "
-   "specified, the help is written into it."},
+   "specified, the help is written into it."
+   "If a file is specified, the documentation is written into and the output "
+   "format is determined depending on the filename suffix. Supported are man "
+   "page, HTML and plain text."},
   {"--help-properties [file]", "Print help for all properties and exit.",
-   "Full documentation for all properties is displayed."},
+   "Full documentation for all properties is displayed."
+   "If a file is specified, the documentation is written into and the output "
+   "format is determined depending on the filename suffix. Supported are man "
+   "page, HTML and plain text."},
   {0,0,0}
 };
 
@@ -179,11 +207,26 @@ int do_cmake(int ac, char** av)
     doc.SetCMakeRoot(hcm.GetCacheDefinition("CMAKE_ROOT"));
     std::vector<cmDocumentationEntry> commands;
     std::vector<cmDocumentationEntry> compatCommands;
-    std::vector<cmDocumentationEntry> properties;
+    std::vector<cmDocumentationEntry> globalProperties;
+    std::vector<cmDocumentationEntry> dirProperties;
+    std::vector<cmDocumentationEntry> targetProperties;
+    std::vector<cmDocumentationEntry> testProperties;
+    std::vector<cmDocumentationEntry> sourceFileProperties;
+    std::vector<cmDocumentationEntry> variableProperties;
+    std::vector<cmDocumentationEntry> cachedVariableProperties;
+
     std::vector<cmDocumentationEntry> generators;
     hcm.GetCommandDocumentation(commands, true, false);
     hcm.GetCommandDocumentation(compatCommands, false, true);
-    hcm.GetPropertiesDocumentation(properties);
+    hcm.GetPropertiesDocumentation(globalProperties, cmProperty::GLOBAL);
+    hcm.GetPropertiesDocumentation(dirProperties, cmProperty::DIRECTORY);
+    hcm.GetPropertiesDocumentation(targetProperties, cmProperty::TARGET);
+    hcm.GetPropertiesDocumentation(testProperties, cmProperty::TEST);
+    hcm.GetPropertiesDocumentation(sourceFileProperties, 
+                                   cmProperty::SOURCE_FILE);
+    hcm.GetPropertiesDocumentation(variableProperties, cmProperty::VARIABLE);
+    hcm.GetPropertiesDocumentation(cachedVariableProperties, 
+                                   cmProperty::CACHED_VARIABLE);
     hcm.GetGeneratorDocumentation(generators);
     doc.SetName("cmake");
     doc.SetNameSection(cmDocumentationName);
@@ -193,10 +236,17 @@ int do_cmake(int ac, char** av)
     doc.SetOptionsSection(cmDocumentationOptions);
     doc.SetCommandsSection(&commands[0]);
     doc.SetCompatCommandsSection(&compatCommands[0]);
-    doc.SetPropertiesSection(&properties[0]);
+    doc.SetPropertiesSection(&globalProperties[0], cmProperty::GLOBAL);
+    doc.SetPropertiesSection(&dirProperties[0], cmProperty::DIRECTORY);
+    doc.SetPropertiesSection(&targetProperties[0], cmProperty::TARGET);
+    doc.SetPropertiesSection(&testProperties[0], cmProperty::TEST);
+    doc.SetPropertiesSection(&sourceFileProperties[0],cmProperty::SOURCE_FILE);
+    doc.SetPropertiesSection(&variableProperties[0],cmProperty::VARIABLE);
+    doc.SetPropertiesSection(&cachedVariableProperties[0],
+                             cmProperty::CACHED_VARIABLE);
     doc.SetSeeAlsoList(cmDocumentationSeeAlso);
     int result = doc.PrintRequestedDocumentation(std::cout)? 0:1;
-    
+
     // If we were run with no arguments, but a CMakeLists.txt file
     // exists, the user may have been trying to use the old behavior
     // of cmake to build a project in-source.  Print a message