|
|
|
|
@ -33,36 +33,65 @@
|
|
|
|
|
<title>Reading</title>
|
|
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem><para> Get and read the relevant sections of the C++ language
|
|
|
|
|
specification. Copies of the full ISO 14882 standard are available on
|
|
|
|
|
line via the ISO mirror site for committee members. Non-members, or
|
|
|
|
|
those who have not paid for the privilege of sitting on the committee
|
|
|
|
|
and sustained their two meeting commitment for voting rights, may get
|
|
|
|
|
a copy of the standard from their respective national standards
|
|
|
|
|
organization. In the USA, this national standards organization is ANSI
|
|
|
|
|
and their web-site is right
|
|
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
Get and read the relevant sections of the C++ language
|
|
|
|
|
specification. Copies of the full ISO 14882 standard are
|
|
|
|
|
available on line via the ISO mirror site for committee
|
|
|
|
|
members. Non-members, or those who have not paid for the
|
|
|
|
|
privilege of sitting on the committee and sustained their
|
|
|
|
|
two meeting commitment for voting rights, may get a copy of
|
|
|
|
|
the standard from their respective national standards
|
|
|
|
|
organization. In the USA, this national standards
|
|
|
|
|
organization is ANSI and their web-site is right
|
|
|
|
|
<ulink url="http://www.ansi.org">here.</ulink>
|
|
|
|
|
(And if you've already registered with them, clicking this link will take you to directly to the place where you can
|
|
|
|
|
<ulink url="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003">buy the standard on-line.)</ulink>
|
|
|
|
|
</para></listitem>
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><para> The library working group bugs, and known defects, can be obtained here:
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
The library working group bugs, and known defects, can
|
|
|
|
|
be obtained here:
|
|
|
|
|
<ulink url="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </ulink>
|
|
|
|
|
</para></listitem>
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><para> The newsgroup dedicated to standardization issues is comp.std.c++: this FAQ for this group is quite useful and can be found <ulink url="http://www.jamesd.demon.co.uk/csc/faq.html"> here </ulink>.
|
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
The newsgroup dedicated to standardization issues is
|
|
|
|
|
comp.std.c++: this FAQ for this group is quite useful and
|
|
|
|
|
can be
|
|
|
|
|
found <ulink url="http://www.jamesd.demon.co.uk/csc/faq.html">
|
|
|
|
|
here </ulink>.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><para> Peruse the <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU Coding Standards</ulink>, and chuckle when you hit the part about "Using Languages Other Than C."
|
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
Peruse
|
|
|
|
|
the <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU
|
|
|
|
|
Coding Standards</ulink>, and chuckle when you hit the part
|
|
|
|
|
about <quote>Using Languages Other Than C</quote>.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><para> Be familiar with the extensions that preceded these general GNU rules. These style issues for libstdc++ can be found in the file C++STYLE, located in the root level of the distribution, or <ulink url="C++STYLE"> here. </ulink>
|
|
|
|
|
</para></listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><para> And last but certainly not least, read the library-specific information found <ulink url="../documentation.html"> here.</ulink>
|
|
|
|
|
</para></listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
Be familiar with the extensions that preceded these
|
|
|
|
|
general GNU rules. These style issues for libstdc++ can be
|
|
|
|
|
found <link linkend="contrib.coding_style">here</link>.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
And last but certainly not least, read the
|
|
|
|
|
library-specific information
|
|
|
|
|
found <link linkend="appendix.porting"> here</link>.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
@ -119,7 +148,6 @@ maintainer above so that progress can be monitored.
|
|
|
|
|
<sect2 id="list.patches" xreflabel="list.patches">
|
|
|
|
|
<title>Submitting Patches</title>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Every patch must have several pieces of information before it can be
|
|
|
|
|
properly evaluated. Ideally (and to ensure the fastest possible
|
|
|
|
|
@ -127,35 +155,162 @@ response from the maintainers) it would have all of these pieces:
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
A description of the bug and how your patch fixes this
|
|
|
|
|
bug. For new features a description of the feature and your
|
|
|
|
|
implementation.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><para> A description of the bug and how your patch fixes this bug. For
|
|
|
|
|
new features a description of the feature and your implementation. </para></listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
A ChangeLog entry as plain text; see the various
|
|
|
|
|
ChangeLog files for format and content. If using you are
|
|
|
|
|
using emacs as your editor, simply position the insertion
|
|
|
|
|
point at the beginning of your change and hit CX-4a to bring
|
|
|
|
|
up the appropriate ChangeLog entry. See--magic! Similar
|
|
|
|
|
functionality also exists for vi.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><para> A ChangeLog entry as plain text; see the various ChangeLog files
|
|
|
|
|
for format and content. If using you are using emacs as your editor,
|
|
|
|
|
simply position the insertion point at the beginning of your change
|
|
|
|
|
and hit CX-4a to bring up the appropriate ChangeLog
|
|
|
|
|
entry. See--magic! Similar functionality also exists for vi. </para></listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
A testsuite submission or sample program that will
|
|
|
|
|
easily and simply show the existing error or test new
|
|
|
|
|
functionality.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><para> A testsuite submission or sample program that will easily and
|
|
|
|
|
simply show the existing error or test new functionality. </para></listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><para> The patch itself. If you are accessing the SVN repository
|
|
|
|
|
use "svn update; svn diff NEW"; else, use "diff -cp OLD NEW"
|
|
|
|
|
... If your version of diff does not support these options, then
|
|
|
|
|
get the latest version of GNU diff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVN Tricks</ulink> wiki page
|
|
|
|
|
has information on customising the output of <code>svn diff</code>.</para></listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><para> When you have all these pieces, bundle them up in a mail message
|
|
|
|
|
and send it to libstdc++@gcc.gnu.org. All patches and related
|
|
|
|
|
discussion should be sent to the libstdc++ mailing list. </para></listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
The patch itself. If you are accessing the SVN
|
|
|
|
|
repository use <command>svn update; svn diff NEW</command>;
|
|
|
|
|
else, use <command>diff -cp OLD NEW</command> ... If your
|
|
|
|
|
version of diff does not support these options, then get the
|
|
|
|
|
latest version of GNU
|
|
|
|
|
diff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVN
|
|
|
|
|
Tricks</ulink> wiki page has information on customising the
|
|
|
|
|
output of <code>svn diff</code>.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
When you have all these pieces, bundle them up in a
|
|
|
|
|
mail message and send it to libstdc++@gcc.gnu.org. All
|
|
|
|
|
patches and related discussion should be sent to the
|
|
|
|
|
libstdc++ mailing list.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
|
|
<sect1 id="contrib.organization" xreflabel="Source Organization">
|
|
|
|
|
<title>Directory Layout and Source Conventions</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
The unpacked source directory of libstdc++ contains the files
|
|
|
|
|
needed to create the GNU C++ Library.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<literallayout>
|
|
|
|
|
It has subdirectories:
|
|
|
|
|
|
|
|
|
|
doc
|
|
|
|
|
Files in HTML and text format that document usage, quirks of the
|
|
|
|
|
implementation, and contributor checklists.
|
|
|
|
|
|
|
|
|
|
include
|
|
|
|
|
All header files for the C++ library are within this directory,
|
|
|
|
|
modulo specific runtime-related files that are in the libsupc++
|
|
|
|
|
directory.
|
|
|
|
|
|
|
|
|
|
include/std
|
|
|
|
|
Files meant to be found by #include <name> directives in
|
|
|
|
|
standard-conforming user programs.
|
|
|
|
|
|
|
|
|
|
include/c
|
|
|
|
|
Headers intended to directly include standard C headers.
|
|
|
|
|
[NB: this can be enabled via --enable-cheaders=c]
|
|
|
|
|
|
|
|
|
|
include/c_global
|
|
|
|
|
Headers intended to include standard C headers in
|
|
|
|
|
the global namespace, and put select names into the std::
|
|
|
|
|
namespace. [NB: this is the default, and is the same as
|
|
|
|
|
--enable-cheaders=c_global]
|
|
|
|
|
|
|
|
|
|
include/c_std
|
|
|
|
|
Headers intended to include standard C headers
|
|
|
|
|
already in namespace std, and put select names into the std::
|
|
|
|
|
namespace. [NB: this is the same as --enable-cheaders=c_std]
|
|
|
|
|
|
|
|
|
|
include/bits
|
|
|
|
|
Files included by standard headers and by other files in
|
|
|
|
|
the bits directory.
|
|
|
|
|
|
|
|
|
|
include/backward
|
|
|
|
|
Headers provided for backward compatibility, such as <iostream.h>.
|
|
|
|
|
They are not used in this library.
|
|
|
|
|
|
|
|
|
|
include/ext
|
|
|
|
|
Headers that define extensions to the standard library. No
|
|
|
|
|
standard header refers to any of them.
|
|
|
|
|
|
|
|
|
|
scripts
|
|
|
|
|
Scripts that are used during the configure, build, make, or test
|
|
|
|
|
process.
|
|
|
|
|
|
|
|
|
|
src
|
|
|
|
|
Files that are used in constructing the library, but are not
|
|
|
|
|
installed.
|
|
|
|
|
|
|
|
|
|
testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*]
|
|
|
|
|
Test programs are here, and may be used to begin to exercise the
|
|
|
|
|
library. Support for "make check" and "make check-install" is
|
|
|
|
|
complete, and runs through all the subdirectories here when this
|
|
|
|
|
command is issued from the build directory. Please note that
|
|
|
|
|
"make check" requires DejaGNU 1.4 or later to be installed. Please
|
|
|
|
|
note that "make check-script" calls the script mkcheck, which
|
|
|
|
|
requires bash, and which may need the paths to bash adjusted to
|
|
|
|
|
work properly, as /bin/bash is assumed.
|
|
|
|
|
|
|
|
|
|
Other subdirectories contain variant versions of certain files
|
|
|
|
|
that are meant to be copied or linked by the configure script.
|
|
|
|
|
Currently these are:
|
|
|
|
|
|
|
|
|
|
config/abi
|
|
|
|
|
config/cpu
|
|
|
|
|
config/io
|
|
|
|
|
config/locale
|
|
|
|
|
config/os
|
|
|
|
|
|
|
|
|
|
In addition, two subdirectories are convenience libraries:
|
|
|
|
|
|
|
|
|
|
libmath
|
|
|
|
|
Support routines needed for C++ math. Only needed if the
|
|
|
|
|
underlying "C" implementation is non-existent, in particular
|
|
|
|
|
required or optimal long double, long long, and C99 functionality.
|
|
|
|
|
|
|
|
|
|
libsupc++
|
|
|
|
|
Contains the runtime library for C++, including exception
|
|
|
|
|
handling and memory allocation and deallocation, RTTI, terminate
|
|
|
|
|
handlers, etc.
|
|
|
|
|
|
|
|
|
|
Note that glibc also has a bits/ subdirectory. We will either
|
|
|
|
|
need to be careful not to collide with names in its bits/
|
|
|
|
|
directory; or rename bits to (e.g.) cppbits/.
|
|
|
|
|
|
|
|
|
|
In files throughout the system, lines marked with an "XXX" indicate
|
|
|
|
|
a bug or incompletely-implemented feature. Lines marked "XXX MT"
|
|
|
|
|
indicate a place that may require attention for multi-thread safety.
|
|
|
|
|
</literallayout>
|
|
|
|
|
|
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
|
|
<sect1 id="contrib.coding_style" xreflabel="Coding Style">
|
|
|
|
|
<title>Coding Style</title>
|
|
|
|
|
<para>
|
|
|
|
|
@ -167,14 +322,14 @@ Identifiers that conflict and should be avoided.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<literallayout>
|
|
|
|
|
This is the list of names <quote>reserved to the
|
|
|
|
|
implementation</quote> that have been claimed by certain
|
|
|
|
|
compilers and system headers of interest, and should not be used
|
|
|
|
|
in the library. It will grow, of course. We generally are
|
|
|
|
|
interested in names that are not all-caps, except for those like
|
|
|
|
|
"_T"
|
|
|
|
|
|
|
|
|
|
This is the list of names "reserved to the implementation" that
|
|
|
|
|
have been claimed by certain compilers and system headers of interest,
|
|
|
|
|
and should not be used in the library. It will grow, of course.
|
|
|
|
|
We generally are interested in names that are not all-caps, except
|
|
|
|
|
for those like "_T"
|
|
|
|
|
|
|
|
|
|
For Solarix:
|
|
|
|
|
For Solaris:
|
|
|
|
|
_B
|
|
|
|
|
_C
|
|
|
|
|
_L
|
|
|
|
|
@ -355,7 +510,6 @@ _opr
|
|
|
|
|
<sect2 id="coding_style.example" xreflabel="coding_style.example">
|
|
|
|
|
<title>By Example</title>
|
|
|
|
|
<literallayout>
|
|
|
|
|
|
|
|
|
|
This library is written to appropriate C++ coding standards. As such,
|
|
|
|
|
it is intended to precede the recommendations of the GNU Coding
|
|
|
|
|
Standard, which can be referenced in full here:
|
|
|
|
|
@ -748,47 +902,65 @@ namespace std
|
|
|
|
|
// doesn't fit in one line.
|
|
|
|
|
}
|
|
|
|
|
} // namespace std
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</literallayout>
|
|
|
|
|
</sect2>
|
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
|
|
<sect1 id="contrib.doc_style" xreflabel="Documentation Style">
|
|
|
|
|
<title>Documentation Style</title>
|
|
|
|
|
<para>
|
|
|
|
|
</para>
|
|
|
|
|
<sect2 id="doc_style.doxygen" xreflabel="doc_style.doxygen">
|
|
|
|
|
<title>Doxygen</title>
|
|
|
|
|
<sect3 id="doxygen.generating" xreflabel="doxygen.generating">
|
|
|
|
|
<title>Generating the Doxygen Files</title>
|
|
|
|
|
<sect3 id="doxygen.prereq" xreflabel="doxygen.prereq">
|
|
|
|
|
<title>Prerequisites</title>
|
|
|
|
|
<para>
|
|
|
|
|
Prerequisite tools are Bash 2.x,
|
|
|
|
|
<ulink url="http://www.doxygen.org/">Doxygen</ulink>, and
|
|
|
|
|
the <ulink url="http://www.gnu.org/software/coreutils/">GNU
|
|
|
|
|
coreutils</ulink>. (GNU versions of find, xargs, and possibly
|
|
|
|
|
sed and grep are used, just because the GNU versions make
|
|
|
|
|
things very easy.)
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>The Makefile rules <code>'make doc-doxygen-html'</code>,
|
|
|
|
|
and <code>'make doc-doxygen-man'</code> in the libstdc++ build
|
|
|
|
|
directory generate the HTML docs, the and the man pages,
|
|
|
|
|
respectively. Prerequisite tools are Bash 2.x,
|
|
|
|
|
<ulink url="http://www.doxygen.org/">Doxygen</ulink>, a working version of <code>g++</code> somewhere in the PATH, and
|
|
|
|
|
the <ulink url="http://www.gnu.org/software/coreutils/">GNU coreutils</ulink>.
|
|
|
|
|
|
|
|
|
|
In addition, to generate the pretty pictures and hierarchy graphs, the
|
|
|
|
|
<ulink url=
|
|
|
|
|
"http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</ulink>
|
|
|
|
|
<para>
|
|
|
|
|
To generate the pretty pictures and hierarchy
|
|
|
|
|
graphs, the
|
|
|
|
|
<ulink url="http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</ulink>
|
|
|
|
|
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.)
|
|
|
|
|
</para>
|
|
|
|
|
</sect3>
|
|
|
|
|
|
|
|
|
|
<sect3 id="doxygen.rules" xreflabel="doxygen.rules">
|
|
|
|
|
<title>Generating the Doxygen Files</title>
|
|
|
|
|
<para>
|
|
|
|
|
The Makefile rules
|
|
|
|
|
</para>
|
|
|
|
|
<screen><userinput>make doc-html-doxygen</userinput></screen>
|
|
|
|
|
<para>
|
|
|
|
|
and
|
|
|
|
|
</para>
|
|
|
|
|
<screen><userinput>make doc-xml-doxygen</userinput></screen>
|
|
|
|
|
<para>
|
|
|
|
|
and
|
|
|
|
|
</para>
|
|
|
|
|
<screen><userinput>make doc-man-doxygen</userinput></screen>
|
|
|
|
|
<para>
|
|
|
|
|
in the libstdc++ build directory generate the HTML docs, the
|
|
|
|
|
XML docs, and the man pages.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>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>.)
|
|
|
|
|
<para>
|
|
|
|
|
Careful observers will see that the Makefile rules simply call
|
|
|
|
|
a script from the source tree, <filename>run_doxygen</filename>, 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 <literal>--help</literal>.)
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>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.
|
|
|
|
|
<para>
|
|
|
|
|
If you wish to tweak the Doxygen settings, do so by editing
|
|
|
|
|
<filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow
|
|
|
|
|
library hackers are written in triple-# comments.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
</sect3>
|
|
|
|
|
@ -796,52 +968,80 @@ namespace std
|
|
|
|
|
<sect3 id="doxygen.markup" xreflabel="doxygen.markup">
|
|
|
|
|
<title>Markup</title>
|
|
|
|
|
|
|
|
|
|
<para>In general, libstdc++ files should be formatted according to the GNU
|
|
|
|
|
C++ Coding Standard rules found in the file
|
|
|
|
|
<ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</ulink>.
|
|
|
|
|
Before any doxygen-specific formatting tweaks are made, please try to make
|
|
|
|
|
sure that the initial formatting is sound.
|
|
|
|
|
<para>
|
|
|
|
|
In general, libstdc++ files should be formatted according to
|
|
|
|
|
the rules found in the
|
|
|
|
|
<link linkend="contrib.coding_style">Coding Standard</link>. Before
|
|
|
|
|
any doxygen-specific formatting tweaks are made, please try to
|
|
|
|
|
make sure that the initial formatting is sound.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>Adding Doxygen markup to a file (informally called "doxygenating") is very
|
|
|
|
|
simple. The Doxygen manual can be found
|
|
|
|
|
<para>
|
|
|
|
|
Adding Doxygen markup to a file (informally called
|
|
|
|
|
<quote>doxygenating</quote>) is very simple. The Doxygen manual can be
|
|
|
|
|
found
|
|
|
|
|
<ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</ulink>.
|
|
|
|
|
We try to use a very-recent version of Doxygen.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>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.
|
|
|
|
|
<para>
|
|
|
|
|
For classes, use
|
|
|
|
|
<classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>
|
|
|
|
|
and <classname>std::pair</classname> as examples. For
|
|
|
|
|
functions, see their member functions, and the free functions
|
|
|
|
|
in <filename>stl_algobase.h</filename>. Member functions of
|
|
|
|
|
other container-like types should read similarly to these
|
|
|
|
|
member functions.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>These points accompany the first list in section 3.1 of the Doxygen manual:
|
|
|
|
|
<para>
|
|
|
|
|
These points accompany the first list in section 3.1 of the
|
|
|
|
|
Doxygen manual:
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<orderedlist>
|
|
|
|
|
<listitem><para>Use the Javadoc style...</para></listitem>
|
|
|
|
|
<listitem><para>...not the Qt style. The intermediate *'s are preferred.</para></listitem>
|
|
|
|
|
<listitem><para>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.</para></listitem>
|
|
|
|
|
<listitem><para>This is disgusting. Don't do this.</para></listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
...not the Qt style. The intermediate *'s are preferred.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
Use the triple-slash style only for one-line comments (the
|
|
|
|
|
<quote>brief</quote> mode). Very recent versions of Doxygen permit
|
|
|
|
|
full-mode comments in triple-slash blocks, but the
|
|
|
|
|
formatting still comes out wonky.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
This is disgusting. Don't do this.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</orderedlist>
|
|
|
|
|
|
|
|
|
|
<para>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.
|
|
|
|
|
<para>
|
|
|
|
|
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 <quote>interesting</quote> effects.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>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.
|
|
|
|
|
<para>
|
|
|
|
|
Use either kind of grouping, as
|
|
|
|
|
appropriate. <filename>doxygroups.cc</filename> exists for this
|
|
|
|
|
purpose. See <filename>stl_iterator.h</filename> for a good example
|
|
|
|
|
of the <quote>other</quote> kind of grouping.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>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.)
|
|
|
|
|
<para>
|
|
|
|
|
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.)
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
</sect3>
|
|
|
|
|
@ -851,24 +1051,122 @@ namespace std
|
|
|
|
|
<sect2 id="doc_style.docbook" xreflabel="doc_style.docbook">
|
|
|
|
|
<title>Docbook</title>
|
|
|
|
|
|
|
|
|
|
<sect3 id="docbook.prereq" xreflabel="docbook.prereq">
|
|
|
|
|
<title>Prerequisites</title>
|
|
|
|
|
<para>
|
|
|
|
|
Editing the DocBook sources requires an XML editor. Many
|
|
|
|
|
exist: some noteable options
|
|
|
|
|
include <command>emacs</command>, <application>Kate</application>,
|
|
|
|
|
or <application>Conglomerate</application>.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Some editors support special <quote>XML Validation</quote>
|
|
|
|
|
modes that can validate the file as it is
|
|
|
|
|
produced. Recommended is the <command>nXML Mode</command>
|
|
|
|
|
for <command>emacs</command>.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Besides an editor, additional DocBook files and XML tools are
|
|
|
|
|
also required.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Access to the DocBook stylesheets and DTD is required. The
|
|
|
|
|
stylesheets are usually packaged by vendor, in something
|
|
|
|
|
like <filename>docbook-style-xsl</filename>. The installation
|
|
|
|
|
directory for this package corresponds to
|
|
|
|
|
the <literal>XSL_STYLE_DIR</literal>
|
|
|
|
|
in <filename>doc/Makefile.am</filename> and defaults
|
|
|
|
|
to <filename class="directory">/usr/share/sgml/docbook/xsl-stylesheets</filename>.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
For procesessing XML, an XML processor and some style
|
|
|
|
|
sheets are necessary. Defaults are <command>xsltproc</command>
|
|
|
|
|
provided by <filename>libxslt</filename>.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
For validating the XML document, you'll need
|
|
|
|
|
something like <command>xmllint</command> and access to the
|
|
|
|
|
DocBook DTD. These are provided
|
|
|
|
|
by a vendor package like <filename>lixml2</filename>.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
For PDF output, something that transforms valid XML to PDF is
|
|
|
|
|
required. Possible solutions include <command>xmlto</command>,
|
|
|
|
|
<ulink url="http://xmlgraphics.apache.org/fop/">Apache
|
|
|
|
|
FOP</ulink>, or <command>prince</command>. Other options are
|
|
|
|
|
listed on the DocBook web <ulink
|
|
|
|
|
url="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</ulink>. Please
|
|
|
|
|
consult the <email>libstdc++@gcc.gnu.org</email> list when
|
|
|
|
|
preparing printed manuals for current best practice and suggestions.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Make sure that the XML documentation and markup is valid for
|
|
|
|
|
any change. This can be done easily, with the validation rules
|
|
|
|
|
in the <filename>Makefile</filename>, which is equivalent to doing:
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<screen>
|
|
|
|
|
<userinput>
|
|
|
|
|
xmllint --noout --valid <filename>xml/index.xml</filename>
|
|
|
|
|
</userinput>
|
|
|
|
|
</screen>
|
|
|
|
|
</sect3>
|
|
|
|
|
|
|
|
|
|
<sect3 id="docbook.rules" xreflabel="docbook.rules">
|
|
|
|
|
<title>Generating the DocBook Files</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
The Makefile rules
|
|
|
|
|
</para>
|
|
|
|
|
<screen><userinput>make doc-html</userinput></screen>
|
|
|
|
|
<para>
|
|
|
|
|
and
|
|
|
|
|
</para>
|
|
|
|
|
<screen><userinput>make doc-pdf</userinput></screen>
|
|
|
|
|
<para>
|
|
|
|
|
and
|
|
|
|
|
</para>
|
|
|
|
|
<screen><userinput>make doc-xml-single</userinput></screen>
|
|
|
|
|
<para>
|
|
|
|
|
and
|
|
|
|
|
</para>
|
|
|
|
|
<screen><userinput>make doc-xml-validate</userinput></screen>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
in the libstdc++ build directory result respectively in the
|
|
|
|
|
following: the generation of an HTML version of all the
|
|
|
|
|
documentation, a PDF version of the same, a single XML
|
|
|
|
|
document, and the results of validating the XML document.
|
|
|
|
|
</para>
|
|
|
|
|
</sect3>
|
|
|
|
|
|
|
|
|
|
<sect3 id="docbook.examples" xreflabel="docbook.examples">
|
|
|
|
|
<title>File Organization and Basics</title>
|
|
|
|
|
|
|
|
|
|
<literallayout>
|
|
|
|
|
<emphasis>Which files are important</emphasis>
|
|
|
|
|
|
|
|
|
|
Which files are important:
|
|
|
|
|
All Docbook files are in the directory
|
|
|
|
|
libstdc++-v3/doc/xml
|
|
|
|
|
|
|
|
|
|
Main page
|
|
|
|
|
Inside this directory, the files of importance:
|
|
|
|
|
spine.xml - index to documentation set
|
|
|
|
|
|
|
|
|
|
manual/spine.xml - index to manual
|
|
|
|
|
manual/*.xml - chapters and sections of the manual
|
|
|
|
|
|
|
|
|
|
manual/*.xml - individual chapters and sections of the manual
|
|
|
|
|
faq.xml - index to FAQ
|
|
|
|
|
api.xml - index to source level / API
|
|
|
|
|
|
|
|
|
|
All *.txml files are template xml files, ie otherwise empty files with
|
|
|
|
|
the correct structure, suitable for filling in.
|
|
|
|
|
the correct structure, suitable for filling in with new information.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Cannonical Writing Style
|
|
|
|
|
<emphasis>Cannonical Writing Style</emphasis>
|
|
|
|
|
|
|
|
|
|
class template
|
|
|
|
|
function template
|
|
|
|
|
@ -880,8 +1178,45 @@ class in namespace std: allocator, not std::allocator
|
|
|
|
|
header file: iostream, not <iostream>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Translation
|
|
|
|
|
<emphasis>General structure</emphasis>
|
|
|
|
|
|
|
|
|
|
<set>
|
|
|
|
|
<book>
|
|
|
|
|
</book>
|
|
|
|
|
|
|
|
|
|
<book>
|
|
|
|
|
<chapter>
|
|
|
|
|
</chapter>
|
|
|
|
|
</book>
|
|
|
|
|
|
|
|
|
|
<book>
|
|
|
|
|
<part>
|
|
|
|
|
<chapter>
|
|
|
|
|
<section>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<sect1>
|
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
|
|
<sect1>
|
|
|
|
|
<sect2>
|
|
|
|
|
</sect2>
|
|
|
|
|
</sect1>
|
|
|
|
|
</chapter>
|
|
|
|
|
|
|
|
|
|
<chapter>
|
|
|
|
|
</chapter>
|
|
|
|
|
</part>
|
|
|
|
|
</book>
|
|
|
|
|
|
|
|
|
|
</set>
|
|
|
|
|
</literallayout>
|
|
|
|
|
</sect3>
|
|
|
|
|
|
|
|
|
|
<sect3 id="docbook.markup" xreflabel="docbook.markup">
|
|
|
|
|
<title>Markup By Example</title>
|
|
|
|
|
|
|
|
|
|
<literallayout>
|
|
|
|
|
HTML to XML rough equivalents
|
|
|
|
|
|
|
|
|
|
<p> <para>
|
|
|
|
|
@ -941,44 +1276,8 @@ Finer gradations of <code>
|
|
|
|
|
<command> <command>g++</command>
|
|
|
|
|
|
|
|
|
|
<errortext> <errortext>foo Concept </errortext>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
General structure
|
|
|
|
|
|
|
|
|
|
<set>
|
|
|
|
|
<book>
|
|
|
|
|
</book>
|
|
|
|
|
|
|
|
|
|
<book>
|
|
|
|
|
<chapter>
|
|
|
|
|
</chapter>
|
|
|
|
|
</book>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<book>
|
|
|
|
|
<part>
|
|
|
|
|
<chapter>
|
|
|
|
|
<section>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<sect1>
|
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
|
|
<sect1>
|
|
|
|
|
<sect2>
|
|
|
|
|
</sect2>
|
|
|
|
|
</sect1>
|
|
|
|
|
</chapter>
|
|
|
|
|
|
|
|
|
|
<chapter>
|
|
|
|
|
</chapter>
|
|
|
|
|
</part>
|
|
|
|
|
</book>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</set>
|
|
|
|
|
|
|
|
|
|
</literallayout>
|
|
|
|
|
</sect3>
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
|
|
</sect1>
|
|
|
|
|
@ -1074,7 +1373,7 @@ header files to be parsed along with every compilation unit.
|
|
|
|
|
|
|
|
|
|
Until "export" is implemented we can put some of the lengthy template
|
|
|
|
|
definitions in #if guards or alternative headers so that users can skip
|
|
|
|
|
over the the full definitions when they need only the ready-instantiated
|
|
|
|
|
over the full definitions when they need only the ready-instantiated
|
|
|
|
|
specializations.
|
|
|
|
|
|
|
|
|
|
To be precise, this means that certain headers which define
|
|
|
|
|
|
Benjamin Kosnik