From 9f16292b6a3a5959b2e7ddb11e54029b02701965 Mon Sep 17 00:00:00 2001 From: Alexander Neundorf Date: Wed, 11 Jul 2007 15:53:58 -0400 Subject: [PATCH] STYLE: sort the property documentation into global/directory/target/test/sourcefile and variable sections Alex --- Source/cmDocumentation.cxx | 179 ++++++++++++++++++++++++++++---- Source/cmDocumentation.h | 27 +++-- Source/cmPropertyDefinition.cxx | 21 +--- Source/cmPropertyDefinition.h | 1 - Source/cmake.cxx | 11 +- Source/cmake.h | 3 +- Source/cmakemain.cxx | 82 ++++++++++++--- 7 files changed, 251 insertions(+), 73 deletions(-) diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index 3858f5e62..7f5e63c74 100644 --- a/Source/cmDocumentation.cxx +++ b/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::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); - return true; + if(entry->name && this->CurrentArgument == entry->name) + { + 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(); - entry->brief; ++entry) + for(const cmDocumentationEntry* + entry = this->GlobalPropertiesSection.GetEntries(); + entry->brief; + ++entry) { if(entry->name) { os << entry->name << std::endl; } } + + for(std::map::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), diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index abfd2582f..bac58b931 100644 --- a/Source/cmDocumentation.h +++ b/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. */ - void SetPropertiesSection(const cmDocumentationEntry*); + + /** Set the global properties for standard document generation. */ + 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 PropertySections; + std::string SeeAlsoString; std::string CMakeRoot; std::vector< char* > ModuleStrings; diff --git a/Source/cmPropertyDefinition.cxx b/Source/cmPropertyDefinition.cxx index cc6c94018..3acd1843f 100644 --- a/Source/cmPropertyDefinition.cxx +++ b/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; - } } diff --git a/Source/cmPropertyDefinition.h b/Source/cmPropertyDefinition.h index cc571eee0..df7aa4bb1 100644 --- a/Source/cmPropertyDefinition.h +++ b/Source/cmPropertyDefinition.h @@ -39,7 +39,6 @@ public: protected: std::string Name; - std::string LongName; std::string ShortDescription; std::string FullDescription; cmProperty::ScopeType Scope; diff --git a/Source/cmake.cxx b/Source/cmake.cxx index 6d7e39870..7e6447691 100644 --- a/Source/cmake.cxx +++ b/Source/cmake.cxx @@ -2165,16 +2165,11 @@ void cmake::GetCommandDocumentation(std::vector& v, v.push_back(empty); } -void cmake::GetPropertiesDocumentation(std::vector& v) +void cmake::GetPropertiesDocumentation(std::vector& v, + cmProperty::ScopeType type) { // get the properties for cmake - std::map::iterator i = - this->PropertyDefinitions.begin(); - for (; i != this->PropertyDefinitions.end(); ++i) - { - i->second.GetPropertiesDocumentation(v); - } - + this->PropertyDefinitions[type].GetPropertiesDocumentation(v); cmDocumentationEntry empty = {0,0,0}; v.push_back(empty); } diff --git a/Source/cmake.h b/Source/cmake.h index f61cf9075..03ee9191c 100644 --- a/Source/cmake.h +++ b/Source/cmake.h @@ -249,7 +249,8 @@ class cmake void GetCommandDocumentation(std::vector& entries, bool withCurrentCommands = true, bool withCompatCommands = true) const; - void GetPropertiesDocumentation(std::vector&); + void GetPropertiesDocumentation(std::vector&, + cmProperty::ScopeType type); void GetGeneratorDocumentation(std::vector&); ///! Set/Get a property of this target file diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx index 4d075fa29..79ae83313 100644 --- a/Source/cmakemain.cxx +++ b/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 " - "specified, the help is written into it."}, + "the --help-command argument followed by a command name. " + "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 " - "specified, the help is written into it."}, + "the --help-module argument followed by a module name. " + "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 commands; std::vector compatCommands; - std::vector properties; + std::vector globalProperties; + std::vector dirProperties; + std::vector targetProperties; + std::vector testProperties; + std::vector sourceFileProperties; + std::vector variableProperties; + std::vector cachedVariableProperties; + std::vector 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