summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2015-11-24 11:54:14 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2015-11-24 11:54:14 +0200
commit469605e872aeca50c7556708de5d50d7e7935d83 (patch)
tree646940c7653065dbb97346f171d097515ec45afd /doc
parent7e9cb673ccfc77c5871292aa5491fc2c2dc2a663 (diff)
Implement support for documentation inside classes
Diffstat (limited to 'doc')
-rw-r--r--doc/cli.113
-rw-r--r--doc/cli.xhtml19
-rw-r--r--doc/language.txt10
3 files changed, 24 insertions, 18 deletions
diff --git a/doc/cli.1 b/doc/cli.1
index a50a1bc..1a89aed 100644
--- a/doc/cli.1
+++ b/doc/cli.1
@@ -112,10 +112,9 @@ documentation string in usage\. By default, in this situation only the first
sentence from the long string is used\.
.IP "\fB--short-usage\fR"
If specified together with \fB--long-usage\fR, generate both short and long
-usage versions\. In this mode, the usage printing functions are called
-\fBprint_short_usage()\fR and \fBprint_long_usage()\fR and for the long usage
-the long documentation string is always used, even if the short version is
-provided\.
+usage versions\. In this mode, the long usage printing function is called
+\fBprint_long_usage()\fR and in its implementation the long documentation
+string is always used, even if the short version is provided\.
.IP "\fB--page-usage\fR \fIname\fR"
Generate the combined usage printing code for the entire page\. Specifically,
this will include all the namespace-level documentation as well as usage for
@@ -134,8 +133,7 @@ documentation variable expansion, for example:
.fi
If both \fB--long-usage\fR and \fB--short-usage\fR options are specified, then
-two functions are generated with the \fB*short_usage()\fR and
-\fB*long_usage()\fR suffixes\.
+the long usage function has the \fB*long_usage()\fR suffix\.
.IP "\fB--option-length\fR \fIlen\fR"
Indent option descriptions \fIlen\fR characters when printing usage\. This is
useful when you have multiple options classes, potentially in separate files,
@@ -148,6 +146,9 @@ However, if you pipe such output through \fBless\fR(1)\fR, it will display
them correctly\.
.IP "\fB--exclude-base\fR"
Exclude base class information from usage and documentation\.
+.IP "\fB--include-base-last\fR"
+Include base class information after derived for usage and documentation\. By
+default, base classes are included first\.
.IP "\fB--class\fR \fIfq-name\fR"
Generate the man page or HTML documentation only for the \fIfq-name\fR options
class\. The \fIfq-name\fR name should be a fully-qualified options class name,
diff --git a/doc/cli.xhtml b/doc/cli.xhtml
index 92f237b..4d80b83 100644
--- a/doc/cli.xhtml
+++ b/doc/cli.xhtml
@@ -153,11 +153,10 @@
<dt><code><b>--short-usage</b></code></dt>
<dd>If specified together with <code><b>--long-usage</b></code>, generate
- both short and long usage versions. In this mode, the usage printing
- functions are called <code><b>print_short_usage()</b></code> and
- <code><b>print_long_usage()</b></code> and for the long usage the long
- documentation string is always used, even if the short version is
- provided.</dd>
+ both short and long usage versions. In this mode, the long usage printing
+ function is called <code><b>print_long_usage()</b></code> and in its
+ implementation the long documentation string is always used, even if the
+ short version is provided.</dd>
<dt><code><b>--page-usage</b></code> <i>name</i></dt>
<dd>Generate the combined usage printing code for the entire page.
@@ -175,9 +174,8 @@
--page-usage print_$name$_ # print_foo_usage() if name is foo</pre>
<p>If both <code><b>--long-usage</b></code> and
- <code><b>--short-usage</b></code> options are specified, then two
- functions are generated with the <code><b>*short_usage()</b></code> and
- <code><b>*long_usage()</b></code> suffixes.</p></dd>
+ <code><b>--short-usage</b></code> options are specified, then the long
+ usage function has the <code><b>*long_usage()</b></code> suffix.</p></dd>
<dt><code><b>--option-length</b></code> <i>len</i></dt>
<dd>Indent option descriptions <i>len</i> characters when printing usage.
@@ -195,6 +193,10 @@
<dt><code><b>--exclude-base</b></code></dt>
<dd>Exclude base class information from usage and documentation.</dd>
+ <dt><code><b>--include-base-last</b></code></dt>
+ <dd>Include base class information after derived for usage and
+ documentation. By default, base classes are included first.</dd>
+
<dt><code><b>--class</b></code> <i>fq-name</i></dt>
<dd>Generate the man page or HTML documentation only for the
<i>fq-name</i> options class. The <i>fq-name</i> name should be a
@@ -356,7 +358,6 @@
where the <code><b>--options-file</b></code> option is specified except
that the shell escaping and quoting is not required. Repeat this option to
specify more than one options file.</p></dd>
-
</dl>
<h1>DIAGNOSTICS</h1>
diff --git a/doc/language.txt b/doc/language.txt
index 16eaa0d..cef7da8 100644
--- a/doc/language.txt
+++ b/doc/language.txt
@@ -47,7 +47,7 @@ namespace-body:
decl-seq(opt)
class-def:
- "class" identifier inheritance-spec(opt) abstract-spec(opt) "{" option-def-seq(opt) "};"
+ "class" identifier inheritance-spec(opt) abstract-spec(opt) "{" class-decl-seq(opt) "};"
inheritance-spec:
":" base-seq
@@ -59,9 +59,13 @@ base-seq:
abstract-spec:
"=" "0"
-option-def-seq:
+class-decl-seq:
+ class-decl
+ class-decl-seq class-decl
+
+class-decl
+ scope-doc
option-def
- option-def-seq option-def
option-def:
type-spec option-name-seq initializer(opt) option-doc(opt) ";"