mirror of git://gcc.gnu.org/git/gcc.git
113 lines
4.6 KiB
HTML
113 lines
4.6 KiB
HTML
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
<title>Build and Writing Guide for libstdc++-v3 Doxygen</title>
|
|
<link href="style.css" rel="stylesheet" type="text/css">
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
<h1>libstdc++-v3 Source Documentation</h1>
|
|
|
|
<p>This file is docs/doxygen/guide.html in the libstdc++-v3 source tree. It
|
|
is not included in the generated pages (no real point to doing that).
|
|
</p>
|
|
|
|
<ul>
|
|
<li><a href="#creating">Creating the pages</a></li>
|
|
<li><a href="#writing">Writing the markup</a></li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="creating"><h2>Creating the pages</h2></a>
|
|
<p>The Makefile rules <code>'make doxygen'</code>,
|
|
<code>'make doxygen-maint'</code>, and <code>'make doxygen-man'</code>
|
|
in the libstdc++-v3 build directory generate the user-level HTML docs, the
|
|
maintainer-level HTML docs, and the man pages, respectively. Prerequisite
|
|
tools are Bash 2.x,
|
|
<a href="http://www.doxygen.org/">
|
|
<!-- snagged from the generated page -->
|
|
<img src="doxygen.png" alt="Doxygen" align=center border=0 width=110 height=53>
|
|
</a>, a working version of <code>g++</code> somewhere in the PATH, and
|
|
the <a href="http://www.gnu.org/software/coreutils/">GNU coreutils</a>.
|
|
|
|
In addition, to generate the pretty pictures, the
|
|
<a href=
|
|
"http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</a>
|
|
package will need to be installed.
|
|
(g++ is used to build a program which manipulates man pages. GNU versions
|
|
of find, xargs, and possibly sed and grep are used, just because the GNU
|
|
versions make things very easy.)
|
|
</p>
|
|
|
|
<p>Careful observers will see that the Makefile rules simply call a script
|
|
from the source tree, <code>run_doxygen</code>, which does the actual work
|
|
of running Doxygen and then (most importantly) massaging the output files.
|
|
If for some reason you prefer to not go through the Makefile, you can call
|
|
this script directly. (Start by passing <code>'--help'</code>.)
|
|
</p>
|
|
|
|
<p>If you wish to tweak the Doxygen settings, do so by editing
|
|
<code>docs/doxygen/user.cfg.in</code>. Notes to v3-hackers are written in
|
|
triple-# comments.
|
|
</p>
|
|
|
|
<a name="writing"><h2>Writing the markup</h2></a>
|
|
<p>In general, libstdc++-v3 files should be formatted according to the GNU
|
|
C++ Coding Standard rules found in the file
|
|
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
|
|
Before any doxygen-specific formatting tweaks are made, please try to make
|
|
sure that the initial formatting is sound.
|
|
</p>
|
|
|
|
<p>Adding Doxygen markup to a file (informally called "doxygenating") is very
|
|
simple. The Doxygen manual can be found
|
|
<a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</a>.
|
|
We try to use a very-recent version of Doxygen.
|
|
</p>
|
|
|
|
<h3>Doxygen style guide</h3>
|
|
<p>[incomplete and constantly evolving]</p>
|
|
|
|
<p>For classes, use deque/vector/list and std::pair as examples. For
|
|
functions, see their member functions, and the free functions in
|
|
<code>stl_algobase.h</code>. Member functions of other container-like
|
|
types should read similarly to these member functions.
|
|
</p>
|
|
|
|
<p>These points accompany the first list in section 3.1 of the Doxygen manual:
|
|
</p>
|
|
<ol>
|
|
<li>Use the Javadoc style...</li>
|
|
<li>...not the Qt style. The intermediate *'s are preferred.</li>
|
|
<li>Use the triple-slash style only for one-line comments (the "brief" mode).
|
|
Very recent versions of Doxygen permit full-mode comments in triple-slash
|
|
blocks, but the formatting still comes out wonky.</li>
|
|
<li>This is disgusting. Don't do this.</li>
|
|
</ol>
|
|
|
|
<p>Use the @-style of commands, not the !-style. Please be careful about
|
|
whitespace in your markup comments. Most of the time it doesn't matter;
|
|
doxygen absorbs most whitespace, and both HTML and *roff are agnostic about
|
|
whitespace. However, in <pre> blocks and @code/@endcode sections,
|
|
spacing can have "interesting" effects.
|
|
</p>
|
|
|
|
<p>Use either kind of grouping, as appropriate. <code>doxygroups.cc</code>
|
|
exists for this purpose. See <code>stl_iterator.h</code> for a good
|
|
example of the "other" kind of grouping.
|
|
</p>
|
|
|
|
<p>Please use markup tags like @p and @a when referring to things such as the
|
|
names of function parameters. Use @e for emphasis when necessary. Use @c
|
|
to refer to other standard names. (Examples of all these abound in the
|
|
present code.)
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|