| 1 |
424 |
jeremybenn |
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
| 2 |
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
| 3 |
|
|
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Documentation Style</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="prev" href="source_code_style.html" title="Coding Style" /><link rel="next" href="source_design_notes.html" title="Design Notes" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Documentation Style</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="source_code_style.html">Prev</a> </td><th width="60%" align="center">Appendix A.
|
| 4 |
|
|
Contributing
|
| 5 |
|
|
|
| 6 |
|
|
</th><td width="20%" align="right"> <a accesskey="n" href="source_design_notes.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Documentation Style"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.doc_style"></a>Documentation Style</h2></div></div></div><div class="sect2" title="Doxygen"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.doxygen"></a>Doxygen</h3></div></div></div><div class="sect3" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.prereq"></a>Prerequisites</h4></div></div></div><p>
|
| 7 |
|
|
Prerequisite tools are Bash 2.x,
|
| 8 |
|
|
<a class="ulink" href="http://www.doxygen.org/" target="_top">Doxygen</a>, and
|
| 9 |
|
|
the <a class="ulink" href="http://www.gnu.org/software/coreutils/" target="_top">GNU
|
| 10 |
|
|
coreutils</a>. (GNU versions of find, xargs, and possibly
|
| 11 |
|
|
sed and grep are used, just because the GNU versions make
|
| 12 |
|
|
things very easy.)
|
| 13 |
|
|
</p><p>
|
| 14 |
|
|
To generate the pretty pictures and hierarchy
|
| 15 |
|
|
graphs, the
|
| 16 |
|
|
<a class="ulink" href="http://www.graphviz.org" target="_top">Graphviz</a>
|
| 17 |
|
|
package will need to be installed.
|
| 18 |
|
|
</p></div><div class="sect3" title="Generating the Doxygen Files"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.rules"></a>Generating the Doxygen Files</h4></div></div></div><p>
|
| 19 |
|
|
The following Makefile rules run Doxygen to generate HTML
|
| 20 |
|
|
docs, XML docs, and the man pages.
|
| 21 |
|
|
</p><p>
|
| 22 |
|
|
</p><pre class="screen"><strong class="userinput"><code>make doc-html-doxygen</code></strong></pre><p>
|
| 23 |
|
|
</p><p>
|
| 24 |
|
|
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-doxygen</code></strong></pre><p>
|
| 25 |
|
|
</p><p>
|
| 26 |
|
|
</p><pre class="screen"><strong class="userinput"><code>make doc-man-doxygen</code></strong></pre><p>
|
| 27 |
|
|
</p><p>
|
| 28 |
|
|
Careful observers will see that the Makefile rules simply call
|
| 29 |
|
|
a script from the source tree, <code class="filename">run_doxygen</code>, which
|
| 30 |
|
|
does the actual work of running Doxygen and then (most
|
| 31 |
|
|
importantly) massaging the output files. If for some reason
|
| 32 |
|
|
you prefer to not go through the Makefile, you can call this
|
| 33 |
|
|
script directly. (Start by passing <code class="literal">--help</code>.)
|
| 34 |
|
|
</p><p>
|
| 35 |
|
|
If you wish to tweak the Doxygen settings, do so by editing
|
| 36 |
|
|
<code class="filename">doc/doxygen/user.cfg.in</code>. Notes to fellow
|
| 37 |
|
|
library hackers are written in triple-# comments.
|
| 38 |
|
|
</p></div><div class="sect3" title="Markup"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.markup"></a>Markup</h4></div></div></div><p>
|
| 39 |
|
|
In general, libstdc++ files should be formatted according to
|
| 40 |
|
|
the rules found in the
|
| 41 |
|
|
<a class="link" href="source_code_style.html" title="Coding Style">Coding Standard</a>. Before
|
| 42 |
|
|
any doxygen-specific formatting tweaks are made, please try to
|
| 43 |
|
|
make sure that the initial formatting is sound.
|
| 44 |
|
|
</p><p>
|
| 45 |
|
|
Adding Doxygen markup to a file (informally called
|
| 46 |
|
|
<span class="quote">“<span class="quote">doxygenating</span>”</span>) is very simple. The Doxygen manual can be
|
| 47 |
|
|
found
|
| 48 |
|
|
<a class="ulink" href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman" target="_top">here</a>.
|
| 49 |
|
|
We try to use a very-recent version of Doxygen.
|
| 50 |
|
|
</p><p>
|
| 51 |
|
|
For classes, use
|
| 52 |
|
|
<code class="classname">deque</code>/<code class="classname">vector</code>/<code class="classname">list</code>
|
| 53 |
|
|
and <code class="classname">std::pair</code> as examples. For
|
| 54 |
|
|
functions, see their member functions, and the free functions
|
| 55 |
|
|
in <code class="filename">stl_algobase.h</code>. Member functions of
|
| 56 |
|
|
other container-like types should read similarly to these
|
| 57 |
|
|
member functions.
|
| 58 |
|
|
</p><p>
|
| 59 |
|
|
Some commentary to accompany
|
| 60 |
|
|
the first list in the <a class="ulink" href="http://www.stack.nl/~dimitri/doxygen/docblocks.html" target="_top">Special
|
| 61 |
|
|
Documentation Blocks</a> section of
|
| 62 |
|
|
the Doxygen manual:
|
| 63 |
|
|
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>For longer comments, use the Javadoc style...</p></li><li class="listitem"><p>
|
| 64 |
|
|
...not the Qt style. The intermediate *'s are preferred.
|
| 65 |
|
|
</p></li><li class="listitem"><p>
|
| 66 |
|
|
Use the triple-slash style only for one-line comments (the
|
| 67 |
|
|
<span class="quote">“<span class="quote">brief</span>”</span> mode).
|
| 68 |
|
|
</p></li><li class="listitem"><p>
|
| 69 |
|
|
This is disgusting. Don't do this.
|
| 70 |
|
|
</p></li></ol></div><p>
|
| 71 |
|
|
Some specific guidelines:
|
| 72 |
|
|
</p><p>
|
| 73 |
|
|
Use the @-style of commands, not the !-style. Please be
|
| 74 |
|
|
careful about whitespace in your markup comments. Most of the
|
| 75 |
|
|
time it doesn't matter; doxygen absorbs most whitespace, and
|
| 76 |
|
|
both HTML and *roff are agnostic about whitespace. However,
|
| 77 |
|
|
in <pre> blocks and @code/@endcode sections, spacing can
|
| 78 |
|
|
have <span class="quote">“<span class="quote">interesting</span>”</span> effects.
|
| 79 |
|
|
</p><p>
|
| 80 |
|
|
Use either kind of grouping, as
|
| 81 |
|
|
appropriate. <code class="filename">doxygroups.cc</code> exists for this
|
| 82 |
|
|
purpose. See <code class="filename">stl_iterator.h</code> for a good example
|
| 83 |
|
|
of the <span class="quote">“<span class="quote">other</span>”</span> kind of grouping.
|
| 84 |
|
|
</p><p>
|
| 85 |
|
|
Please use markup tags like @p and @a when referring to things
|
| 86 |
|
|
such as the names of function parameters. Use @e for emphasis
|
| 87 |
|
|
when necessary. Use @c to refer to other standard names.
|
| 88 |
|
|
(Examples of all these abound in the present code.)
|
| 89 |
|
|
</p><p>
|
| 90 |
|
|
Complicated math functions should use the multi-line
|
| 91 |
|
|
format. An example from <code class="filename">random.h</code>:
|
| 92 |
|
|
</p><p>
|
| 93 |
|
|
</p><div class="literallayout"><p><br />
|
| 94 |
|
|
/**<br />
|
| 95 |
|
|
* @brief A model of a linear congruential random number generator.<br />
|
| 96 |
|
|
*<br />
|
| 97 |
|
|
* @f[<br />
|
| 98 |
|
|
* x_{i+1}\leftarrow(ax_{i} + c) \bmod m <br />
|
| 99 |
|
|
* @f]<br />
|
| 100 |
|
|
*/<br />
|
| 101 |
|
|
</p></div><p>
|
| 102 |
|
|
</p><p>
|
| 103 |
|
|
Be careful about using certain, special characters when
|
| 104 |
|
|
writing Doxygen comments. Single and double quotes, and
|
| 105 |
|
|
separators in filenames are two common trouble spots. When in
|
| 106 |
|
|
doubt, consult the following table.
|
| 107 |
|
|
</p><div class="table"><a id="id645775"></a><p class="title"><b>Table A.1. HTML to Doxygen markup comparison</b></p><div class="table-contents"><table summary="HTML to Doxygen markup comparison" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Doxygen</th></tr></thead><tbody><tr><td align="left">\</td><td align="left">\\</td></tr><tr><td align="left">"</td><td align="left">\"</td></tr><tr><td align="left">'</td><td align="left">\'</td></tr><tr><td align="left"><i></td><td align="left">@a word</td></tr><tr><td align="left"><b></td><td align="left">@b word</td></tr><tr><td align="left"><code></td><td align="left">@c word</td></tr><tr><td align="left"><em></td><td align="left">@a word</td></tr><tr><td align="left"><em></td><td align="left"><em>two words or more</em></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="sect2" title="Docbook"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.docbook"></a>Docbook</h3></div></div></div><div class="sect3" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><p>
|
| 108 |
|
|
Editing the DocBook sources requires an XML editor. Many
|
| 109 |
|
|
exist: some notable options
|
| 110 |
|
|
include <span class="command"><strong>emacs</strong></span>, <span class="application">Kate</span>,
|
| 111 |
|
|
or <span class="application">Conglomerate</span>.
|
| 112 |
|
|
</p><p>
|
| 113 |
|
|
Some editors support special <span class="quote">“<span class="quote">XML Validation</span>”</span>
|
| 114 |
|
|
modes that can validate the file as it is
|
| 115 |
|
|
produced. Recommended is the <span class="command"><strong>nXML Mode</strong></span>
|
| 116 |
|
|
for <span class="command"><strong>emacs</strong></span>.
|
| 117 |
|
|
</p><p>
|
| 118 |
|
|
Besides an editor, additional DocBook files and XML tools are
|
| 119 |
|
|
also required.
|
| 120 |
|
|
</p><p>
|
| 121 |
|
|
Access to the DocBook stylesheets and DTD is required. The
|
| 122 |
|
|
stylesheets are usually packaged by vendor, in something
|
| 123 |
|
|
like <code class="filename">docbook-style-xsl</code>. To exactly match
|
| 124 |
|
|
generated output, please use a version of the stylesheets
|
| 125 |
|
|
equivalent
|
| 126 |
|
|
to <code class="filename">docbook-style-xsl-1.74.0-5</code>. The
|
| 127 |
|
|
installation directory for this package corresponds to
|
| 128 |
|
|
the <code class="literal">XSL_STYLE_DIR</code>
|
| 129 |
|
|
in <code class="filename">doc/Makefile.am</code> and defaults
|
| 130 |
|
|
to <code class="filename">/usr/share/sgml/docbook/xsl-stylesheets</code>.
|
| 131 |
|
|
</p><p>
|
| 132 |
|
|
For processing XML, an XML processor and some style
|
| 133 |
|
|
sheets are necessary. Defaults are <span class="command"><strong>xsltproc</strong></span>
|
| 134 |
|
|
provided by <code class="filename">libxslt</code>.
|
| 135 |
|
|
</p><p>
|
| 136 |
|
|
For validating the XML document, you'll need
|
| 137 |
|
|
something like <span class="command"><strong>xmllint</strong></span> and access to the
|
| 138 |
|
|
DocBook DTD. These are provided
|
| 139 |
|
|
by a vendor package like <code class="filename">libxml2</code>.
|
| 140 |
|
|
</p><p>
|
| 141 |
|
|
For PDF output, something that transforms valid XML to PDF is
|
| 142 |
|
|
required. Possible solutions include <span class="command"><strong>xmlto</strong></span>,
|
| 143 |
|
|
<a class="ulink" href="http://xmlgraphics.apache.org/fop/" target="_top">Apache
|
| 144 |
|
|
FOP</a>, or <span class="command"><strong>prince</strong></span>. Other options are
|
| 145 |
|
|
listed on the DocBook web <a class="ulink" href="http://wiki.docbook.org/topic/DocBookPublishingTools" target="_top">pages</a>. Please
|
| 146 |
|
|
consult the <code class="email"><<a class="email" href="mailto:libstdc++@gcc.gnu.org">libstdc++@gcc.gnu.org</a>></code> list when
|
| 147 |
|
|
preparing printed manuals for current best practice and suggestions.
|
| 148 |
|
|
</p><p>
|
| 149 |
|
|
Make sure that the XML documentation and markup is valid for
|
| 150 |
|
|
any change. This can be done easily, with the validation rules
|
| 151 |
|
|
in the <code class="filename">Makefile</code>, which is equivalent to doing:
|
| 152 |
|
|
</p><pre class="screen">
|
| 153 |
|
|
<strong class="userinput"><code>
|
| 154 |
|
|
xmllint --noout --valid <code class="filename">xml/index.xml</code>
|
| 155 |
|
|
</code></strong>
|
| 156 |
|
|
</pre></div><div class="sect3" title="Generating the DocBook Files"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.rules"></a>Generating the DocBook Files</h4></div></div></div><p>
|
| 157 |
|
|
The following Makefile rules generate (in order): an HTML
|
| 158 |
|
|
version of all the documentation, a PDF version of the same, a
|
| 159 |
|
|
single XML document, and the result of validating the entire XML
|
| 160 |
|
|
document.
|
| 161 |
|
|
</p><p>
|
| 162 |
|
|
</p><pre class="screen"><strong class="userinput"><code>make doc-html</code></strong></pre><p>
|
| 163 |
|
|
</p><p>
|
| 164 |
|
|
</p><pre class="screen"><strong class="userinput"><code>make doc-pdf</code></strong></pre><p>
|
| 165 |
|
|
</p><p>
|
| 166 |
|
|
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-single</code></strong></pre><p>
|
| 167 |
|
|
</p><p>
|
| 168 |
|
|
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-validate</code></strong></pre><p>
|
| 169 |
|
|
</p></div><div class="sect3" title="File Organization and Basics"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.examples"></a>File Organization and Basics</h4></div></div></div><div class="literallayout"><p><br />
|
| 170 |
|
|
<span class="emphasis"><em>Which files are important</em></span><br />
|
| 171 |
|
|
<br />
|
| 172 |
|
|
All Docbook files are in the directory<br />
|
| 173 |
|
|
libstdc++-v3/doc/xml<br />
|
| 174 |
|
|
<br />
|
| 175 |
|
|
Inside this directory, the files of importance:<br />
|
| 176 |
|
|
spine.xml - index to documentation set<br />
|
| 177 |
|
|
manual/spine.xml - index to manual<br />
|
| 178 |
|
|
manual/*.xml - individual chapters and sections of the manual<br />
|
| 179 |
|
|
faq.xml - index to FAQ<br />
|
| 180 |
|
|
api.xml - index to source level / API <br />
|
| 181 |
|
|
<br />
|
| 182 |
|
|
All *.txml files are template xml files, i.e., otherwise empty files with<br />
|
| 183 |
|
|
the correct structure, suitable for filling in with new information.<br />
|
| 184 |
|
|
<br />
|
| 185 |
|
|
<span class="emphasis"><em>Canonical Writing Style</em></span><br />
|
| 186 |
|
|
<br />
|
| 187 |
|
|
class template<br />
|
| 188 |
|
|
function template<br />
|
| 189 |
|
|
member function template<br />
|
| 190 |
|
|
(via C++ Templates, Vandevoorde)<br />
|
| 191 |
|
|
<br />
|
| 192 |
|
|
class in namespace std: allocator, not std::allocator<br />
|
| 193 |
|
|
<br />
|
| 194 |
|
|
header file: iostream, not <iostream><br />
|
| 195 |
|
|
<br />
|
| 196 |
|
|
<br />
|
| 197 |
|
|
<span class="emphasis"><em>General structure</em></span><br />
|
| 198 |
|
|
<br />
|
| 199 |
|
|
<set><br />
|
| 200 |
|
|
<book><br />
|
| 201 |
|
|
</book><br />
|
| 202 |
|
|
<br />
|
| 203 |
|
|
<book><br />
|
| 204 |
|
|
<chapter><br />
|
| 205 |
|
|
</chapter><br />
|
| 206 |
|
|
</book><br />
|
| 207 |
|
|
<br />
|
| 208 |
|
|
<book> <br />
|
| 209 |
|
|
<part><br />
|
| 210 |
|
|
<chapter><br />
|
| 211 |
|
|
<section><br />
|
| 212 |
|
|
</section><br />
|
| 213 |
|
|
<br />
|
| 214 |
|
|
<sect1><br />
|
| 215 |
|
|
</sect1><br />
|
| 216 |
|
|
<br />
|
| 217 |
|
|
<sect1><br />
|
| 218 |
|
|
<sect2><br />
|
| 219 |
|
|
</sect2><br />
|
| 220 |
|
|
</sect1><br />
|
| 221 |
|
|
</chapter><br />
|
| 222 |
|
|
<br />
|
| 223 |
|
|
<chapter><br />
|
| 224 |
|
|
</chapter><br />
|
| 225 |
|
|
</part> <br />
|
| 226 |
|
|
</book><br />
|
| 227 |
|
|
<br />
|
| 228 |
|
|
</set><br />
|
| 229 |
|
|
</p></div></div><div class="sect3" title="Markup By Example"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.markup"></a>Markup By Example</h4></div></div></div><p>
|
| 230 |
|
|
Complete details on Docbook markup can be found in the DocBook Element
|
| 231 |
|
|
Reference, <a class="ulink" href="http://www.docbook.org/tdg/en/html/part2.html" target="_top">online</a>. An
|
| 232 |
|
|
incomplete reference for HTML to Docbook conversion is detailed in the
|
| 233 |
|
|
table below.
|
| 234 |
|
|
</p><div class="table"><a id="id724766"></a><p class="title"><b>Table A.2. HTML to Docbook XML markup comparison</b></p><div class="table-contents"><table summary="HTML to Docbook XML markup comparison" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Docbook</th></tr></thead><tbody><tr><td align="left"><p></td><td align="left"><para></td></tr><tr><td align="left"><pre></td><td align="left"><computeroutput>, <programlisting>,
|
| 235 |
|
|
<literallayout></td></tr><tr><td align="left"><ul></td><td align="left"><itemizedlist></td></tr><tr><td align="left"><ol></td><td align="left"><orderedlist></td></tr><tr><td align="left"><il></td><td align="left"><listitem></td></tr><tr><td align="left"><dl></td><td align="left"><variablelist></td></tr><tr><td align="left"><dt></td><td align="left"><term></td></tr><tr><td align="left"><dd></td><td align="left"><listitem></td></tr><tr><td align="left"><a href=""></td><td align="left"><ulink url=""></td></tr><tr><td align="left"><code></td><td align="left"><literal>, <programlisting></td></tr><tr><td align="left"><strong></td><td align="left"><emphasis></td></tr><tr><td align="left"><em></td><td align="left"><emphasis></td></tr><tr><td align="left">"</td><td align="left"><quote></td></tr></tbody></table></div></div><br class="table-break" /><p>
|
| 236 |
|
|
And examples of detailed markup for which there are no real HTML
|
| 237 |
|
|
equivalents are listed in the table below.
|
| 238 |
|
|
</p><div class="table"><a id="id631420"></a><p class="title"><b>Table A.3. Docbook XML Element Use</b></p><div class="table-contents"><table summary="Docbook XML Element Use" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Element</th><th align="left">Use</th></tr></thead><tbody><tr><td align="left"><structname></td><td align="left"><structname>char_traits</structname></td></tr><tr><td align="left"><classname></td><td align="left"><classname>string</classname></td></tr><tr><td align="left"><function></td><td align="left">
|
| 239 |
|
|
<p><function>clear()</function></p>
|
| 240 |
|
|
<p><function>fs.clear()</function></p>
|
| 241 |
|
|
</td></tr><tr><td align="left"><type></td><td align="left"><type>long long</type></td></tr><tr><td align="left"><varname></td><td align="left"><varname>fs</varname></td></tr><tr><td align="left"><literal></td><td align="left">
|
| 242 |
|
|
<p><literal>-Weffc++</literal></p>
|
| 243 |
|
|
<p><literal>rel_ops</literal></p>
|
| 244 |
|
|
</td></tr><tr><td align="left"><constant></td><td align="left">
|
| 245 |
|
|
<p><constant>_GNU_SOURCE</constant></p>
|
| 246 |
|
|
<p><constant>3.0</constant></p>
|
| 247 |
|
|
</td></tr><tr><td align="left"><command></td><td align="left"><command>g++</command></td></tr><tr><td align="left"><errortext></td><td align="left"><errortext>In instantiation of</errortext></td></tr><tr><td align="left"><filename></td><td align="left">
|
| 248 |
|
|
<p><filename class="headerfile">ctype.h</filename></p>
|
| 249 |
|
|
<p><filename class="directory">/home/gcc/build</filename></p>
|
| 250 |
|
|
<p><filename class="libraryfile">libstdc++.so</filename></p>
|
| 251 |
|
|
</td></tr></tbody></table></div></div><br class="table-break" /></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="source_code_style.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="source_design_notes.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Coding Style </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Design Notes</td></tr></table></div></body></html>
|
