| 1 |
20 |
jlechner |
<!DOCTYPE html
|
| 2 |
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
| 3 |
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
| 4 |
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
| 5 |
|
|
<head>
|
| 6 |
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
| 7 |
|
|
<title>Build and Writing Guide for libstdc++-v3 Doxygen</title>
|
| 8 |
|
|
<link href="style.css" rel="stylesheet" type="text/css">
|
| 9 |
|
|
</head>
|
| 10 |
|
|
|
| 11 |
|
|
<body bgcolor="#ffffff">
|
| 12 |
|
|
|
| 13 |
|
|
<h1>libstdc++-v3 Source Documentation</h1>
|
| 14 |
|
|
|
| 15 |
|
|
<p>This file is docs/doxygen/guide.html in the libstdc++-v3 source tree. It
|
| 16 |
|
|
is not included in the generated pages (no real point to doing that).
|
| 17 |
|
|
</p>
|
| 18 |
|
|
|
| 19 |
|
|
<ul>
|
| 20 |
|
|
<li><a href="#creating">Creating the pages</a></li>
|
| 21 |
|
|
<li><a href="#writing">Writing the markup</a></li>
|
| 22 |
|
|
</ul>
|
| 23 |
|
|
|
| 24 |
|
|
<hr />
|
| 25 |
|
|
|
| 26 |
|
|
<a name="creating"><h2>Creating the pages</h2></a>
|
| 27 |
|
|
<p>The Makefile rules <code>'make doxygen'</code>,
|
| 28 |
|
|
<code>'make doxygen-maint'</code>, and <code>'make doxygen-man'</code>
|
| 29 |
|
|
in the libstdc++-v3 build directory generate the user-level HTML docs, the
|
| 30 |
|
|
maintainer-level HTML docs, and the man pages, respectively. Prerequisite
|
| 31 |
|
|
tools are Bash 2.x,
|
| 32 |
|
|
<a href="http://www.doxygen.org/">
|
| 33 |
|
|
<!-- snagged from the generated page -->
|
| 34 |
|
|
<img src="doxygen.png" alt="Doxygen" align=center border=0 width=110 height=53>
|
| 35 |
|
|
</a>, a working version of <code>g++</code> somewhere in the PATH, and
|
| 36 |
|
|
the <a href="http://www.gnu.org/software/coreutils/">GNU coreutils</a>.
|
| 37 |
|
|
|
| 38 |
|
|
In addition, to generate the pretty pictures, the
|
| 39 |
|
|
<a href=
|
| 40 |
|
|
"http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</a>
|
| 41 |
|
|
package will need to be installed.
|
| 42 |
|
|
(g++ is used to build a program which manipulates man pages. GNU versions
|
| 43 |
|
|
of find, xargs, and possibly sed and grep are used, just because the GNU
|
| 44 |
|
|
versions make things very easy.)
|
| 45 |
|
|
</p>
|
| 46 |
|
|
|
| 47 |
|
|
<p>Careful observers will see that the Makefile rules simply call a script
|
| 48 |
|
|
from the source tree, <code>run_doxygen</code>, which does the actual work
|
| 49 |
|
|
of running Doxygen and then (most importantly) massaging the output files.
|
| 50 |
|
|
If for some reason you prefer to not go through the Makefile, you can call
|
| 51 |
|
|
this script directly. (Start by passing <code>'--help'</code>.)
|
| 52 |
|
|
</p>
|
| 53 |
|
|
|
| 54 |
|
|
<p>If you wish to tweak the Doxygen settings, do so by editing
|
| 55 |
|
|
<code>docs/doxygen/user.cfg.in</code>. Notes to v3-hackers are written in
|
| 56 |
|
|
triple-# comments.
|
| 57 |
|
|
</p>
|
| 58 |
|
|
|
| 59 |
|
|
<a name="writing"><h2>Writing the markup</h2></a>
|
| 60 |
|
|
<p>In general, libstdc++-v3 files should be formatted according to the GNU
|
| 61 |
|
|
C++ Coding Standard rules found in the file
|
| 62 |
|
|
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
|
| 63 |
|
|
Before any doxygen-specific formatting tweaks are made, please try to make
|
| 64 |
|
|
sure that the initial formatting is sound.
|
| 65 |
|
|
</p>
|
| 66 |
|
|
|
| 67 |
|
|
<p>Adding Doxygen markup to a file (informally called "doxygenating") is very
|
| 68 |
|
|
simple. The Doxygen manual can be found
|
| 69 |
|
|
<a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</a>.
|
| 70 |
|
|
We try to use a very-recent version of Doxygen.
|
| 71 |
|
|
</p>
|
| 72 |
|
|
|
| 73 |
|
|
<h3>Doxygen style guide</h3>
|
| 74 |
|
|
<p>[incomplete and constantly evolving]</p>
|
| 75 |
|
|
|
| 76 |
|
|
<p>For classes, use deque/vector/list and std::pair as examples. For
|
| 77 |
|
|
functions, see their member functions, and the free functions in
|
| 78 |
|
|
<code>stl_algobase.h</code>. Member functions of other container-like
|
| 79 |
|
|
types should read similarly to these member functions.
|
| 80 |
|
|
</p>
|
| 81 |
|
|
|
| 82 |
|
|
<p>These points accompany the first list in section 3.1 of the Doxygen manual:
|
| 83 |
|
|
</p>
|
| 84 |
|
|
<ol>
|
| 85 |
|
|
<li>Use the Javadoc style...</li>
|
| 86 |
|
|
<li>...not the Qt style. The intermediate *'s are preferred.</li>
|
| 87 |
|
|
<li>Use the triple-slash style only for one-line comments (the "brief" mode).
|
| 88 |
|
|
Very recent versions of Doxygen permit full-mode comments in triple-slash
|
| 89 |
|
|
blocks, but the formatting still comes out wonky.</li>
|
| 90 |
|
|
<li>This is disgusting. Don't do this.</li>
|
| 91 |
|
|
</ol>
|
| 92 |
|
|
|
| 93 |
|
|
<p>Use the @-style of commands, not the !-style. Please be careful about
|
| 94 |
|
|
whitespace in your markup comments. Most of the time it doesn't matter;
|
| 95 |
|
|
doxygen absorbs most whitespace, and both HTML and *roff are agnostic about
|
| 96 |
|
|
whitespace. However, in <pre> blocks and @code/@endcode sections,
|
| 97 |
|
|
spacing can have "interesting" effects.
|
| 98 |
|
|
</p>
|
| 99 |
|
|
|
| 100 |
|
|
<p>Use either kind of grouping, as appropriate. <code>doxygroups.cc</code>
|
| 101 |
|
|
exists for this purpose. See <code>stl_iterator.h</code> for a good
|
| 102 |
|
|
example of the "other" kind of grouping.
|
| 103 |
|
|
</p>
|
| 104 |
|
|
|
| 105 |
|
|
<p>Please use markup tags like @p and @a when referring to things such as the
|
| 106 |
|
|
names of function parameters. Use @e for emphasis when necessary. Use @c
|
| 107 |
|
|
to refer to other standard names. (Examples of all these abound in the
|
| 108 |
|
|
present code.)
|
| 109 |
|
|
</p>
|
| 110 |
|
|
|
| 111 |
|
|
</body>
|
| 112 |
|
|
</html>
|
