From 89ce153311d9163bbc356927346c0b30e158a75f Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 9 Nov 2010 10:46:51 +0200 Subject: Add support for suppressing documentation for undocumented options --- NEWS | 3 ++ cli/html.cxx | 6 +++- cli/man.cxx | 6 +++- cli/options.cli | 8 ++++- cli/options.cxx | 99 ++++++++++++++++++++++++++++++++++++++------------------- cli/options.hxx | 4 +++ cli/options.ixx | 6 ++++ cli/source.cxx | 17 +++++++--- 8 files changed, 109 insertions(+), 40 deletions(-) diff --git a/NEWS b/NEWS index dc3ce70..b2389ac 100644 --- a/NEWS +++ b/NEWS @@ -3,6 +3,9 @@ Version 1.2.0 * New option, --generate-specifier, triggers the generation of functions for determining whether the option was specified on the command line. + * New option, --suppress-undocumented, suppresses the generation of + documentation entries for undocumented options. + * New option, --cli-namespace, allows changing of the namespace for the generated CLI support types. diff --git a/cli/html.cxx b/cli/html.cxx index c603dcf..9304fee 100644 --- a/cli/html.cxx +++ b/cli/html.cxx @@ -16,6 +16,11 @@ namespace { using semantics::names; + type::doc_list const& doc (o.doc ()); + + if (options.suppress_undocumented () && doc.empty ()) + return; + names& n (o.named ()); os << "
"; @@ -30,7 +35,6 @@ namespace os << ""; - type::doc_list const& doc (o.doc ()); string type (o.type ().name ()); std::set arg_set; diff --git a/cli/man.cxx b/cli/man.cxx index 821fc15..ab979ab 100644 --- a/cli/man.cxx +++ b/cli/man.cxx @@ -16,6 +16,11 @@ namespace { using semantics::names; + type::doc_list const& doc (o.doc ()); + + if (options.suppress_undocumented () && doc.empty ()) + return; + names& n (o.named ()); os << ".IP \"\\fB"; @@ -30,7 +35,6 @@ namespace os << "\\fP"; - type::doc_list const& doc (o.doc ()); string type (o.type ().name ()); std::set arg_set; diff --git a/cli/options.cli b/cli/options.cli index 8955e08..ccafa68 100644 --- a/cli/options.cli +++ b/cli/options.cli @@ -47,6 +47,12 @@ class options made inline. This option suppresses creation of the inline file." }; + bool --suppress-undocumented + { + "Suppress the generation of documentation entries for undocumented + options." + }; + bool --suppress-usage { "Suppress the generation of the usage printing code." @@ -69,7 +75,7 @@ class options std::string --cli-namespace = "::cli" { - "" + "", "Generate the CLI support types in the namespace (\cb{cli} by default). The namespace can be nested, for example \cb{details::cli}. If the namespace is empty, then the support types are generated in diff --git a/cli/options.cxx b/cli/options.cxx index 6a14702..093fd55 100644 --- a/cli/options.cxx +++ b/cli/options.cxx @@ -529,6 +529,7 @@ options (int& argc, generate_specifier_ (), generate_file_scanner_ (), suppress_inline_ (), + suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), option_length_ (0), @@ -573,6 +574,7 @@ options (int start, generate_specifier_ (), generate_file_scanner_ (), suppress_inline_ (), + suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), option_length_ (0), @@ -617,6 +619,7 @@ options (int& argc, generate_specifier_ (), generate_file_scanner_ (), suppress_inline_ (), + suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), option_length_ (0), @@ -663,6 +666,7 @@ options (int start, generate_specifier_ (), generate_file_scanner_ (), suppress_inline_ (), + suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), option_length_ (0), @@ -705,6 +709,7 @@ options (::cli::scanner& s, generate_specifier_ (), generate_file_scanner_ (), suppress_inline_ (), + suppress_undocumented_ (), suppress_usage_ (), long_usage_ (), option_length_ (0), @@ -737,69 +742,97 @@ options (::cli::scanner& s, void options:: print_usage (::std::ostream& os) { - os << "--help Print usage information and exit." << ::std::endl; + os << "--help Print usage information and exit." << ::std::endl; - os << "--version Print version and exit." << ::std::endl; + os << "--version Print version and exit." << ::std::endl; - os << "--output-dir|-o Write the generated files to instead of the current directory." << ::std::endl; + os << "--output-dir|-o Write the generated files to instead of the" << ::std::endl + << " current directory." << ::std::endl; - os << "--generate-modifier Generate option value modifiers in addition to accessors." << ::std::endl; + os << "--generate-modifier Generate option value modifiers in addition to" << ::std::endl + << " accessors." << ::std::endl; - os << "--generate-specifier Generate functions for determining whether the option was specified on the command line." << ::std::endl; + os << "--generate-specifier Generate functions for determining whether the" << ::std::endl + << " option was specified on the command line." << ::std::endl; - os << "--generate-file-scanner Generate the 'argv_file_scanner' implementation." << ::std::endl; + os << "--generate-file-scanner Generate the 'argv_file_scanner' implementation." << ::std::endl; - os << "--suppress-inline Generate all functions non-inline." << ::std::endl; + os << "--suppress-inline Generate all functions non-inline." << ::std::endl; - os << "--suppress-usage Suppress the generation of the usage printing code." << ::std::endl; + os << "--suppress-undocumented Suppress the generation of documentation entries" << ::std::endl + << " for undocumented options." << ::std::endl; - os << "--long-usage If no short documentation string is provided, use the complete long documentation string in usage." << ::std::endl; + os << "--suppress-usage Suppress the generation of the usage printing code." << ::std::endl; - os << "--option-length Indent option descriptions characters when printing usage." << ::std::endl; + os << "--long-usage If no short documentation string is provided, use" << ::std::endl + << " the complete long documentation string in usage." << ::std::endl; - os << "--cli-namespace Generate the CLI support types in the namespace ('cli' by default). The namespace can be nested, for example 'details::cli'. If the namespace is empty, then the support types are generated in the global namespace." << std::endl; + os << "--option-length Indent option descriptions characters when" << ::std::endl + << " printing usage." << ::std::endl; - os << "--generate-cxx Generate C++ code." << ::std::endl; + os << "--cli-namespace Generate the CLI support types in the " << ::std::endl + << " namespace ('cli' by default)." << ::std::endl; - os << "--generate-man Generate documentation in the man page format." << ::std::endl; + os << "--generate-cxx Generate C++ code." << ::std::endl; - os << "--generate-html Generate documentation in the HTML format." << ::std::endl; + os << "--generate-man Generate documentation in the man page format." << ::std::endl; - os << "--man-prologue Insert the content of at the beginning of the man page file." << ::std::endl; + os << "--generate-html Generate documentation in the HTML format." << ::std::endl; - os << "--man-epilogue Insert the content of at the end of the man page file." << ::std::endl; + os << "--man-prologue Insert the content of at the beginning of" << ::std::endl + << " the man page file." << ::std::endl; - os << "--html-prologue Insert the content of at the beginning of the HTML file." << ::std::endl; + os << "--man-epilogue Insert the content of at the end of the man" << ::std::endl + << " page file." << ::std::endl; - os << "--html-epilogue Insert the content of at the end of the HTML file." << ::std::endl; + os << "--html-prologue Insert the content of at the beginning of" << ::std::endl + << " the HTML file." << ::std::endl; - os << "--class Generate the man page or HTML documentation only for the options class." << ::std::endl; + os << "--html-epilogue Insert the content of at the end of the HTML" << ::std::endl + << " file." << ::std::endl; - os << "--stdout Write output to STDOUT instead of a file." << ::std::endl; + os << "--class Generate the man page or HTML documentation only" << ::std::endl + << " for the options class." << ::std::endl; - os << "--hxx-suffix Use instead of the default '.hxx' to construct the name of the generated header file." << ::std::endl; + os << "--stdout Write output to STDOUT instead of a file." << ::std::endl; - os << "--ixx-suffix Use instead of the default '.ixx' to construct the name of the generated inline file." << ::std::endl; + os << "--hxx-suffix Use instead of the default '.hxx' to" << ::std::endl + << " construct the name of the generated header file." << ::std::endl; - os << "--cxx-suffix Use instead of the default '.cxx' to construct the name of the generated source file." << ::std::endl; + os << "--ixx-suffix Use instead of the default '.ixx' to" << ::std::endl + << " construct the name of the generated inline file." << ::std::endl; - os << "--man-suffix Use instead of the default '.1' to construct the name of the generated man page file." << ::std::endl; + os << "--cxx-suffix Use instead of the default '.cxx' to" << ::std::endl + << " construct the name of the generated source file." << ::std::endl; - os << "--html-suffix Use instead of the default '.html' to construct the name of the generated HTML file." << ::std::endl; + os << "--man-suffix Use instead of the default '.1' to" << ::std::endl + << " construct the name of the generated man page file." << ::std::endl; - os << "--option-prefix Use instead of the default '-' as an option prefix." << ::std::endl; + os << "--html-suffix Use instead of the default '.html' to" << ::std::endl + << " construct the name of the generated HTML file." << ::std::endl; - os << "--option-separator Use instead of the default '--' as an optional separator between options and arguments." << ::std::endl; + os << "--option-prefix Use instead of the default '-' as an" << ::std::endl + << " option prefix." << ::std::endl; - os << "--include-with-brackets Use angle brackets (<>) instead of quotes (\"\") in the generated '#include' directives." << ::std::endl; + os << "--option-separator Use instead of the default '--' as an" << ::std::endl + << " optional separator between options and arguments." << ::std::endl; - os << "--include-prefix Add to the generated '#include' directive paths." << ::std::endl; + os << "--include-with-brackets Use angle brackets (<>) instead of quotes (\"\") in" << ::std::endl + << " the generated '#include' directives." << ::std::endl; - os << "--guard-prefix Add to the generated header inclusion guards." << ::std::endl; + os << "--include-prefix Add to the generated '#include' directive" << ::std::endl + << " paths." << ::std::endl; - os << "--reserved-name = Add with an optional replacement to the list of names that should not be used as identifiers." << ::std::endl; + os << "--guard-prefix Add to the generated header inclusion" << ::std::endl + << " guards." << ::std::endl; - os << "--options-file Read additional options from with each option appearing on a separate line optionally followed by space and an option value." << ::std::endl; + os << "--reserved-name = Add with an optional replacement to" << ::std::endl + << " the list of names that should not be used as" << ::std::endl + << " identifiers." << ::std::endl; + + os << "--options-file Read additional options from with each" << ::std::endl + << " option appearing on a separate line optionally" << ::std::endl + << " followed by space and an option value." << ::std::endl; } typedef @@ -828,6 +861,8 @@ struct _cli_options_map_init &::cli::thunk< options, bool, &options::generate_file_scanner_ >; _cli_options_map_["--suppress-inline"] = &::cli::thunk< options, bool, &options::suppress_inline_ >; + _cli_options_map_["--suppress-undocumented"] = + &::cli::thunk< options, bool, &options::suppress_undocumented_ >; _cli_options_map_["--suppress-usage"] = &::cli::thunk< options, bool, &options::suppress_usage_ >; _cli_options_map_["--long-usage"] = diff --git a/cli/options.hxx b/cli/options.hxx index 5c5e1bb..d8a880d 100644 --- a/cli/options.hxx +++ b/cli/options.hxx @@ -342,6 +342,9 @@ class options suppress_inline () const; const bool& + suppress_undocumented () const; + + const bool& suppress_usage () const; const bool& @@ -435,6 +438,7 @@ class options bool generate_specifier_; bool generate_file_scanner_; bool suppress_inline_; + bool suppress_undocumented_; bool suppress_usage_; bool long_usage_; std::size_t option_length_; diff --git a/cli/options.ixx b/cli/options.ixx index f79d75e..9c9afda 100644 --- a/cli/options.ixx +++ b/cli/options.ixx @@ -204,6 +204,12 @@ suppress_inline () const } inline const bool& options:: +suppress_undocumented () const +{ + return this->suppress_undocumented_; +} + +inline const bool& options:: suppress_usage () const { return this->suppress_usage_; diff --git a/cli/source.cxx b/cli/source.cxx index f68f2d3..7d85859 100644 --- a/cli/source.cxx +++ b/cli/source.cxx @@ -115,6 +115,11 @@ namespace { using semantics::names; + type::doc_list const& doc (o.doc ()); + + if (options.suppress_undocumented () && doc.empty ()) + return; + size_t l (0); names& n (o.named ()); @@ -132,10 +137,8 @@ namespace { l++; // ' ' seperator - type::doc_list const& d (o.doc ()); - - if (d.size () > 0) - l += d[0].size (); + if (doc.size () > 0) + l += doc[0].size (); else l += 5; // } @@ -163,6 +166,11 @@ namespace { using semantics::names; + type::doc_list const& doc (o.doc ()); + + if (options.suppress_undocumented () && doc.empty ()) + return; + size_t l (0); names& n (o.named ()); @@ -180,7 +188,6 @@ namespace l += i->size (); } - type::doc_list const& doc (o.doc ()); string type (o.type ().name ()); if (type != "bool") -- cgit v1.1