This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
[libstdc++] Update docs for snapshot
- From: Phil Edwards <phil at jaj dot com>
- To: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Date: Fri, 1 Feb 2002 19:12:41 -0500
- Subject: [libstdc++] Update docs for snapshot
Tweaks to the wwwdocs side of things are forthcoming.
2002-02-01 Phil Edwards <pme@gcc.gnu.org>
* docs/html/documentation.html: Update for 3.0.96.
* docs/html/faq/index.html: Update for 3.0.96.
* docs/html/faq/index.txt: Regenerated.
* docs/doxygen/TODO: Update notes.
* docs/html/17_intro/howto.html: Initial impl-specific listing.
Index: docs/doxygen/TODO
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/TODO,v
retrieving revision 1.3
diff -u -3 -p -r1.3 TODO
--- TODO 2002/01/28 22:13:03 1.3
+++ TODO 2002/02/02 00:15:46
@@ -23,18 +23,19 @@ c25 stl_algo.h (lots of stuf
c26 <complex>, <valarray>, stl_numeric.h[26.4], Note A
c27 Untouched
-backward/ Not scanned by doxygen. Should it be?
+backward/* Not scanned by doxygen. Should it be? Doubtful.
-ext/ Some of the SGI algorithm/functional extensions.
+ext/* Some of the SGI algorithm/functional extensions.
All of rope/hashing/slist need docs.
-__gnu_cxx Tricky.
+__gnu_cxx Tricky. Right now ext/* are in this namespace.
[1.3.5] "implementation-defined behavior: behavior ... that depends
on the implementation *and that each implementation shall
document*." [my emphasis] Not all implementation choices
have been thus described; doxygen is not necessarily the
- appropriate place for such descriptions, either.
+ appropriate place for such descriptions, either. I suggest
+ adding this list to the Chapter 17 HOWTO.
-----------------------------------------------------------
@@ -46,8 +47,11 @@ do not have the C code (to which the dox
this would need to be done in entirely separate files, a la doxygroups.cc.
B) Huge chunks of containers and strings are described in common "Tables"
-in the standard. How to reproduce this information?
-
+in the standard. How to reproduce this information? I suspect we should
+simply write some HTML tables (say, one <table> per Table per file), and
+use doxygen hooks like @pre and @see to reference the tables. Then the
+individual classes would do like the standard does, and only document
+members for which additional info is available.
STYLE:
Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.12
diff -u -3 -p -r1.12 documentation.html
--- documentation.html 2001/12/19 21:36:32 1.12
+++ documentation.html 2002/02/02 00:15:46
@@ -20,24 +20,27 @@
using the Doxygen tool. These are useful for examining the signatures
of public member functions for the library classes, etc.
</p>
-<p>One collection is for the GCC 3.0 release,
- <code>libstdc++-doxygen-3.0.tar.gz</code> (3.8MB),
- <a href="libstdc++-doxygen-3.0/index.html">viewable online</a>.
- The latest collection is for the libstdc++ 3.0.95 snapshot release,
- <a href="libstdc++-doxygen-USERS-3.0.95/index.html">viewable online</a>.
- Other collections for 3.0.95 exist on the FTP sites, but are not
- viewable online.
-</p>
<p>The collections are available in the libstdc++ snapshots directory at
<code><URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/></code>.
You will almost certainly need to use one of the
<a href="http://gcc.gnu.org/mirrors.html";>mirror sites</a> to download
- the tarball. After unpacking, simply load
- libstdc++-doxygen-*/index.html
+ the tarball. After unpacking, simply load libstdc++-html-*/index.html
into a browser. Feedback (and additional documentation!) is welcome.
+</p>
+<p>The available user-level collections are also viewable online:
+ <ul>
+ <li><a href="libstdc++-doxygen-3.0/index.html">docs for the 3.0 release</a>
+ <li><a href="libstdc++-html-USERS-3.0.96/index.html">docs for the most
+ recent libstdc++ snapshot (3.0.96)</a>
+ <li><a href="latest-doxygen/index.html">"the latest collection"</a>
+ (snapshot collection or later; see the date on the first page)
+ </ul>
+ Other collections (man pages, maintainer docs) are only available on the
+ FTP sites.
</p>
-<p>With 3.0.95, an initial set of man pages are also available in the same
- directory as the doxygen collections. Start with <code>Intro(3)</code>.
+
+<p>Beginning with 3.0.95, an initial set of man pages are also available in
+ the same place as the HTML collections. Start with <code>Intro(3)</code>.
</p>
<hr>
Index: docs/html/17_intro/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/howto.html,v
retrieving revision 1.18
diff -u -3 -p -r1.18 howto.html
--- howto.html 2001/11/28 00:02:04 1.18
+++ howto.html 2002/02/02 00:15:46
@@ -28,6 +28,7 @@
<li><a href="#3">The Standard C++ library and multithreading</a>
<li><a href="#4"><code><foo></code> vs <code><foo.h></code></a>
<li><a href="porting-howto.html">Porting HOWTO</a>
+ <li><a href="#5">Behavior specific to libstdc++-v3</a>
</ul>
<hr>
@@ -157,6 +158,69 @@
really have new names. Marshall Cline's C++ FAQ Lite has a good
explanation in
<a href="http://www.cerfnet.com/~mpcline/On-Line-C++-FAQ/coding-standards.html#[25.4]";>item [25.4]</a>.
+ </p>
+ <p>Return <a href="#top">to top of page</a> or
+ <a href="../faq/index.html">to the FAQ</a>.
+ </p>
+
+<hr>
+<h2><a name="5">Behavior specific to libstdc++-v3</a></h2>
+ <p>The ISO standard defines the following:
+ <blockquote><dl>
+ <dt><code>[1.3.5] implementation-defined behavior</code>
+ <dd>behavior, for a well-formed program construct and correct data, that
+ depends on the implementation <strong>and that each implementation
+ shall document</strong>.
+ </dl></blockquote>
+ We do so here, for the C++ library only. Behavior of the compiler,
+ linker, runtime loader, and other elements of "the
+ implementation" are documented elsewhere.
+ </p>
+ <p>For each entry, we give the section number of the standard, when
+ applicable. This list is known to be incomplet and inkorrekt.
+ </p>
+ <p><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best
+ discussed in the various sections on multithreading (see above).
+ </p>
+ <!-- [17.4.4.8]/3 says any function that doesn't have an exception-spec
+ can throw whatever we want; see also its footnote. Let's list those
+ in the sections where the function itself occurs.
+ -->
+ <p><strong>[18.1]/4</strong> The type of <code>NULL</code> is described
+ <a href="../18_support/howto.html#1">here</a>.
+ </p>
+ <p><strong>[18.3]/8</strong> Even though it's listed in the library
+ sections, libstdc++-v3 has zero control over what the cleanup code hands
+ back to the runtime loader. Talk to the compiler people. :-)
+ </p>
+ <p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br>
+ <strong>[18.5.2]/5</strong> (bad_cast),<br>
+ <strong>[18.5.3]/5</strong> (bad_typeid),<br>
+ <strong>[18.6.1]/8</strong> (exception),<br>
+ <strong>[18.6.2.1]/5</strong> (bad_exception): The <code>what()</code>
+ member function of class <code>std::exception</code>, and these other
+ classes publicly derived from it, simply returns the name of the
+ class. But they are the <em>mangled</em> names.
+<!-- demangler bug fixed yet? -->
+ (The classes in <code><stdexcept></code> have constructors which
+ require a string argument to use in <code>what()</code> calls, so the
+ question does not arise in most user-defined exceptions.)
+ </p>
+ <p><strong></strong>
+ </p>
+ <p><strong></strong>
+ </p>
+ <p><strong></strong>
+ </p>
+ <p><strong></strong>
+ </p>
+ <p><strong></strong>
+ </p>
+ <p><strong></strong>
+ </p>
+ <p><strong></strong>
+ </p>
+ <p><strong></strong>
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
Index: docs/html/faq/index.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/faq/index.html,v
retrieving revision 1.29
diff -u -3 -p -r1.29 index.html
--- index.html 2001/12/19 21:36:33 1.29
+++ index.html 2002/02/02 00:15:46
@@ -15,8 +15,12 @@
<h1 class="centered">libstdc++ Frequently Asked Questions</h1>
<p>The latest version of this document is always available at
-<a href="http://gcc.gnu.org/onlinedocs/libstdc++/faq/";>
-http://gcc.gnu.org/onlinedocs/libstdc++/faq/</a>.</p>
+ <a href="http://gcc.gnu.org/onlinedocs/libstdc++/faq/";>
+ http://gcc.gnu.org/onlinedocs/libstdc++/faq/</a>. The main documentation
+ page is at
+ <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html";>
+ http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html</a>.
+</p>
<p>To the <a href="http://gcc.gnu.org/libstdc++/";>libstdc++-v3 homepage</a>.
@@ -105,7 +109,7 @@ http://gcc.gnu.org/onlinedocs/libstdc++/
library reaches stable plateaus, it is captured in a snapshot
and released. The current release is
<a href="http://gcc.gnu.org/libstdc++/download.html";>the
- twelfth snapshot</a>. For those who want to see exactly how
+ thirteenth snapshot</a>. For those who want to see exactly how
far the project has come, or just want the latest
bleeding-edge code, the up-to-date source is available over
anonymous CVS, and can even be browsed over the Web (see below).
@@ -161,7 +165,7 @@ http://gcc.gnu.org/onlinedocs/libstdc++/
<hr>
<h2><a name="1_4">1.4 How do I get libstdc++?</a></h2>
- <p>The twelfth (and latest) snapshot of libstdc++-v3 is
+ <p>The thirteenth (and latest) snapshot of libstdc++-v3 is
<a href="http://gcc.gnu.org/libstdc++/download.html";>available via
ftp</a>.
</p>
@@ -460,13 +464,26 @@ which is no longer available, thanks dej
<h2><a name="4_1">4.1 What works already?</a></h2>
<p>This is a verbatim clip from the "Status" section
- of the RELEASE-NOTES for the latest snapshot.
+ of the RELEASE-NOTES for the latest snapshot. For a list of
+ fixed bugs, see that file.
</p>
<!-- Yeah, I meant that "verbatim clip" thing literally... :-) -->
<pre>
-New:
+New in 3.0.96:
+---
+- more doxygen documentation.
+- extensions moved out of namespace std
+- HPUX long long support
+- more string optimizations
+- support for NetBSD cross compiles
+- concept_check merge from boost
+- header simplification
+- named locale bug shakeout
+- thread testsuite
+
+New in 3.0.95:
---
- add S390, m68k, x86-64 support.
- doxygen documentation has been extended, including man pages.