78a5388739
2006-11-29 Benjamin Kosnik <bkoz@redhat.com> * include/ext/throw_allocator.h: Consistent @file markup. * include/ext/type_traits.h: Same. * include/debug/hash_map: Same. * include/debug/hash_multimap.h: Same. * include/debug/set.h: Same. * include/debug/hash_set.h: Same. * include/debug/formatter.h: Same. * include/debug/bitset: Same. * include/debug/set: Same. * include/debug/multiset.h: Same. * include/debug/safe_sequence.h: Same. * include/debug/hash_set: Same. * include/debug/functions.h: Same. * include/debug/safe_base.h: Same. * include/debug/hash_multiset.h: Same. * include/debug/safe_iterator.tcc: Same. * include/debug/vector: Same. * include/debug/map.h: Same. * include/debug/deque: Same. * include/debug/hash_map.h: Same. * include/debug/string: Same. * include/debug/macros.h: Same. * include/debug/list: Same. * include/debug/debug.h: Same. * include/debug/map: Same. * include/debug/safe_iterator.h: Same. * include/debug/multimap.h: Same. * config/cpu/generic/atomicity_mutex/atomicity.h: Same. * config/cpu/generic/atomicity_builtins/atomicity.h: Same. * config/cpu/generic/atomic_word.h: Same. * include/tr1/memory: Same. * include/tr1/random: Same. * include/std/std_queue.h: Same. * include/std/std_iterator.h: Same. * include/std/std_bitset.h: Same. * include/std/std_set.h: Same. * include/std/std_vector.h: Same. * include/std/std_deque.h: Same. * include/std/std_utility.h: Same. * include/std/std_stack.h: Same. * include/std/std_string.h: Same. * include/std/std_list.h: Same. * include/std/std_map.h: Same. * libsupc++/typeinfo: Same. * libsupc++/exception: Same. * libsupc++/exception_defines.h: Same. * libsupc++/new: Same. * include/ext/bitmap_allocator.h: Change namespace __balloc to __detail. * src/bitmap_allocator.cc: Same. * include/bits/cpp_type_traits.h: Change __true_type and __false_type from global to namespace std scope. * include/ext/slist: Same. * include/ext/vstring.h: Same. * include/ext/vstring.tcc: Same. * include/ext/rc_string_base.h: Same. * include/ext/sso_string_base.h: Same. * include/bits/codecvt.h: Adjust markup so that correct namespace scope information is in all files. * include/bits/locale_facets.h: Same. Include ctype_base directly. * config/os/windiss/ctype_base.h: Add in namespace markup. * config/os/newlib/ctype_base.h: Same. * config/os/aix/ctype_base.h: Same. * config/os/vxworks/ctype_base.h: Same. * config/os/hpux/ctype_base.h: Same. * config/os/mingw32/ctype_base.h: Same. * config/os/gnu-linux/ctype_base.h: Same. * config/os/tpf/ctype_base.h: Same. * config/os/uclibc/ctype_base.h: Same. * config/os/djgpp/ctype_base.h: Same. * config/os/qnx/qnx6.1/ctype_base.h: Same. * config/os/bsd/netbsd/ctype_base.h: Same. * config/os/bsd/darwin/ctype_base.h: Same. * config/os/bsd/freebsd/ctype_base.h: Same. * config/os/irix/irix5.2/ctype_base.h: Same. * config/os/irix/irix6.5/ctype_base.h: Same. * config/os/solaris/solaris2.5/ctype_base.h: Same. * config/os/solaris/solaris2.6/ctype_base.h: Same. * config/os/solaris/solaris2.7/ctype_base.h: Same. * config/os/generic/ctype_base.h: Same. * include/tr1/mu_iterate.h: Same. * include/tr1/tuple: Same. * include/tr1/tuple_iterate.h: Same. * include/tr1/tuple_defs.h: Same. * include/tr1/random.tcc: Same. * include/tr1/functional: Same. * include/tr1/functional_iterate.h: Same. * testsuite/ext/type_traits/remove_unsigned_integer_neg.cc: Line number changes. * testsuite/ext/type_traits/add_unsigned_floating_neg.cc: Same. * testsuite/ext/type_traits/remove_unsigned_floating_neg.cc: Same. * testsuite/ext/type_traits/add_unsigned_integer_neg.cc: Same. * docs/doxygen/user.cfg.in: Update to doxygen 1.5.1. * docs/html/17_intro/license.html: Updated info for generated docs. * docs/doxygen/guide.html: Adjust. * docs/doxygen/run_doxygen: Adjust. * docs/doxygen/mainpage.html: Same. * docs/doxygen/doxygroups.cc: Same. * docs/doxygen/Intro.3: Same. * docs/doxygen/tables.html: Same. From-SVN: r119334
113 lines
4.5 KiB
HTML
113 lines
4.5 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++ Doxygen</title>
|
|
<link href="style.css" rel="stylesheet" type="text/css">
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
<h1>libstdc++ Source Documentation</h1>
|
|
|
|
<p>This file is docs/doxygen/guide.html in the libstdc++ 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++ 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++ 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>
|