Commit fd58f127 by Phil Edwards

[multiple changes]

2002-02-04  Phil Edwards  <pme@gcc.gnu.org>

	* docs/doxygen/TODO:  Impl-defined behavior now documented...
	* docs/html/17_intro/howto.html:  ...here.
	* docs/doxygen/mainpage.doxy:  Remove, rename...
	* docs/doxygen/mainpage.html:  ...to this.  Tweak HTML, add license.
	* docs/doxygen/style.css:  Add small text.
	* docs/doxygen/run_doxygen:  Adjust for new mainpage.
	* docs/doxygen/user.cfg.in:  Likewise.

2002-02-04  Stephan Buys  <s.buys@icon.co.za>

	* include/bits/stl_map.h:  Initial doxygen markup.
	* include/std/std_fstream.h:  Initial doxygen markup.

From-SVN: r49502
parent ebbb0a63
2002-02-04 Phil Edwards <pme@gcc.gnu.org>
* docs/doxygen/TODO: Impl-defined behavior now documented...
* docs/html/17_intro/howto.html: ...here.
* docs/doxygen/mainpage.doxy: Remove, rename...
* docs/doxygen/mainpage.html: ...to this. Tweak HTML, add license.
* docs/doxygen/style.css: Add small text.
* docs/doxygen/run_doxygen: Adjust for new mainpage.
* docs/doxygen/user.cfg.in: Likewise.
2002-02-04 Stephan Buys <s.buys@icon.co.za>
* include/bits/stl_map.h: Initial doxygen markup.
* include/std/std_fstream.h: Initial doxygen markup.
2002-02-04 Paolo Carlini <pcarlini@unitus.it> 2002-02-04 Paolo Carlini <pcarlini@unitus.it>
libstdc++/5579 libstdc++/5579
......
...@@ -30,13 +30,6 @@ ext/* Some of the SGI algorithm/functional extensions. ...@@ -30,13 +30,6 @@ ext/* Some of the SGI algorithm/functional extensions.
__gnu_cxx Tricky. Right now ext/* are in this namespace. __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. I suggest
adding this list to the Chapter 17 HOWTO.
----------------------------------------------------------- -----------------------------------------------------------
NOTES: NOTES:
......
/*! \mainpage <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>Main Page</title>
<link href="style.css" rel="stylesheet" type="text/css">
</head>
<body bgcolor="#ffffff">
<!--
Originally generated by Doxygen 1.2.12.
This used to be surrounded by /* */ marks and tagged with @mainpage, so
that Doxygen would create the index page from it. HOWEVER, Doxygen
ignores all but the most basic HTML tags, and even with those it strips
all the attributes. (See, the HTML you write for @mainpage isn't used
directly; it all gets run through Doxygen and re-output.) So lots of
tags were all being mangled.
Funk 'dat. Now we let Doxygen do whateer it feels like doing for the
index page, and then we just flat copy this over top of it. Voila!
Tags actually work like they're supposed to.
-->
<h1>libstdc++-v3 Source Documentation</h1>
<h2> Documentation Overview </h2> <h2> Documentation Overview </h2>
<p class="smallertext">Generated 2002-02-04.</p>
<p>There are two types of documentation for libstdc++-v3. One is the <p>There are two types of documentation for libstdc++-v3. One is the
distribution documentation, which can be read online at distribution documentation, which can be read online at
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html</a> <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html</a>
...@@ -26,8 +51,12 @@ ...@@ -26,8 +51,12 @@
The Makefile rule <code> 'make The Makefile rule <code> 'make
doxygen' </code> in the libstdc++-v3 build directory generates these pages doxygen' </code> in the libstdc++-v3 build directory generates these pages
using a tool called, appropriately enough, Doxygen. To learn more about using a tool called, appropriately enough, Doxygen. To learn more about
Doxygen, take a look at <a href="http://www.doxygen.org">the Doxygen Doxygen, take a look at
webpage</a>. <a href="http://www.doxygen.org/">
<!-- snagged from the generated page -->
<img src="doxygen.gif" alt="the Doxygen homepage"
align=center border=0 width=110 height=53>
</a>
</p> </p>
<p>The libstdc++-v3 configuration files needed to generate doxygen output <p>The libstdc++-v3 configuration files needed to generate doxygen output
...@@ -71,6 +100,31 @@ href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>. ...@@ -71,6 +100,31 @@ href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
</ul> </ul>
</p> </p>
*/
<h2> License, Copyright, and Other Lawyerly Verbosity </h2>
<p>The libstdc++-v3 documentation is released under
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/license.html">
these terms</a>.
</p>
<p>Part of the generated documentation involved comments
and notes from SGI, who says we gotta say this:
<blockquote>
Permission to use, copy, modify, distribute and sell this software and its
documentation for any purpose is hereby granted without fee, provided
that the below copyright notice appears in all copies and that both
the copyright notice and this permission notice appear in supporting
documentation. Silicon Graphics makes no representations about the
suitability of this software for any purpose. It is provided "as is"
without express or implied warranty.
<br><br>
Copyright &copy; 1994
Hewlett-Packard Company
</blockquote>
</p>
<p>Part of the generated documentation is quoted from the C++ standard, which
is copyright 1998 by Information Technology Industry Council.
</p>
</body>
</html>
...@@ -146,6 +146,7 @@ set -e ...@@ -146,6 +146,7 @@ set -e
set +e set +e
test $do_html = yes && { test $do_html = yes && {
cp ${srcdir}/docs/doxygen/mainpage.html ${outdir}/html_${mode}/index.html
echo :: echo ::
echo :: HTML pages begin with echo :: HTML pages begin with
echo :: ${outdir}/html_${mode}/index.html echo :: ${outdir}/html_${mode}/index.html
......
...@@ -21,3 +21,4 @@ FONT.comment { color: #800000 } ...@@ -21,3 +21,4 @@ FONT.comment { color: #800000 }
FONT.preprocessor { color: #806020 } FONT.preprocessor { color: #806020 }
FONT.stringliteral { color: #002080 } FONT.stringliteral { color: #002080 }
FONT.charliteral { color: #008080 } FONT.charliteral { color: #008080 }
.smallertext { font-size: smaller }
...@@ -296,8 +296,7 @@ WARN_LOGFILE = ...@@ -296,8 +296,7 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories # directories like "/usr/src/myproject". Separate the files or directories
# with spaces. # with spaces.
INPUT = @srcdir@/docs/doxygen/mainpage.doxy \ INPUT = @srcdir@/docs/doxygen/doxygroups.cc \
@srcdir@/docs/doxygen/doxygroups.cc \
@srcdir@/src \ @srcdir@/src \
@srcdir@/libsupc++/exception \ @srcdir@/libsupc++/exception \
@srcdir@/libsupc++/new \ @srcdir@/libsupc++/new \
......
...@@ -165,26 +165,28 @@ ...@@ -165,26 +165,28 @@
<hr> <hr>
<h2><a name="5">Behavior specific to libstdc++-v3</a></h2> <h2><a name="5">Behavior specific to libstdc++-v3</a></h2>
<p>The ISO standard defines the following: <p>The ISO standard defines the following phrase:
<blockquote><dl> <blockquote><dl>
<dt><code>[1.3.5] implementation-defined behavior</code> <dt><code>[1.3.5] implementation-defined behavior</code>
<dd>behavior, for a well-formed program construct and correct data, that <dd>behavior, for a well-formed program construct and correct data, that
depends on the implementation <strong>and that each implementation depends on the implementation <strong>and that each implementation
shall document</strong>. shall document</strong>.
</dl></blockquote> </dl></blockquote>
We do so here, for the C++ library only. Behavior of the compiler, We do so here, for the C++ library only. Behavior of the compiler,
linker, runtime loader, and other elements of &quot;the linker, runtime loader, and other elements of &quot;the
implementation&quot; are documented elsewhere. implementation&quot; are documented elsewhere. Everything listed in
Annex B, Implemenation Qualities, are also part of the compiler, not
the library.
</p> </p>
<p>For each entry, we give the section number of the standard, when <p>For each entry, we give the section number of the standard, when
applicable. This list is known to be incomplet and inkorrekt. applicable. This list is probably incomplet and inkorrekt.
</p> </p>
<p><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best <p><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best
discussed in the various sections on multithreading (see above). discussed in the various sections on multithreading (see above).
</p> </p>
<!-- [17.4.4.8]/3 says any function that doesn't have an exception-spec <!-- [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 can throw whatever we want; see also its footnote. Let's list those
in the sections where the function itself occurs. in the sections where the function itself occurs.
--> -->
<p><strong>[18.1]/4</strong> The type of <code>NULL</code> is described <p><strong>[18.1]/4</strong> The type of <code>NULL</code> is described
<a href="../18_support/howto.html#1">here</a>. <a href="../18_support/howto.html#1">here</a>.
...@@ -200,27 +202,66 @@ ...@@ -200,27 +202,66 @@
<strong>[18.6.2.1]/5</strong> (bad_exception): The <code>what()</code> <strong>[18.6.2.1]/5</strong> (bad_exception): The <code>what()</code>
member function of class <code>std::exception</code>, and these other member function of class <code>std::exception</code>, and these other
classes publicly derived from it, simply returns the name of the classes publicly derived from it, simply returns the name of the
class. But they are the <em>mangled</em> names. class. But they are the <em>mangled</em> names; you will need to call
<!-- demangler bug fixed yet? --> <code>c++filt</code> and pass the names as command-line parameters to
demangle them.
(The classes in <code>&lt;stdexcept&gt;</code> have constructors which (The classes in <code>&lt;stdexcept&gt;</code> have constructors which
require a string argument to use in <code>what()</code> calls, so the require an argument to use later for <code>what()</code> calls, so the
question does not arise in most user-defined exceptions.) question does not arise in most user-defined exceptions.)
</p> </p>
<p><strong></strong> <p><strong>[18.5.1]/7</strong> The return value of
<code>std::type_info::name()</code> is the mangled type name (see the
previous entry for more).
</p> </p>
<p><strong></strong> <p><strong>[20.1.5]/5</strong> <em>&quot;Implementors are encouraged to
supply libraries that can accept allocators that encapsulate more
general memory models and that support non-equal instances. In such
implementations, any requirements imposed on allocators by containers
beyond those requirements that appear in Table 32, and the semantics
of containers and algorithms when allocator instances compare
non-equal, are implementation-defined.&quot;</em> As yet we don't
have any allocators which compare non-equal, so we can't describe how
they behave.
</p> </p>
<p><strong></strong> <p><strong>[21.1.3.1]/3,4</strong>,<br>
<strong>[21.1.3.2]/2</strong>,<br>
<strong>[23.*]'s foo::iterator</strong>,<br>
<strong>[27.*]'s foo::*_type</strong>,<br>
<strong>others...</strong>
Nope, these types are called implementation-defined because you
shouldn't be taking advantage of their underlying types. Listing them
here would defeat the purpose. :-)
</p> </p>
<p><strong></strong> <p><strong>[21.1.3.1]/5</strong> I don't really know about the mbstate_t
stuff... see the chapter 22 notes for what does exist.
</p> </p>
<p><strong></strong> <p><strong>[22.*]</strong> Anything and everything we have on locale
implemenation will be described
<a href="../22_locale/howto.html">over here</a>.
</p> </p>
<p><strong></strong> <p><strong>[26.2.8]/9</strong> I have no idea what
<code>complex&lt;T&gt;</code>'s pow(0,0) returns.
</p> </p>
<p><strong></strong> <p><strong>[27.4.2.4]/2</strong> Calling
<code>std::ios_base::sync_with_stdio</code> after I/O has already been
performed on the standard stream objects will
flush the buffers, and <!-- this line might go away -->
destroy and recreate the underlying buffer instances. Whether or not
the previously-written I/O is destroyed in this process depends mostly
on the --enable-libio choice: for stdio, if the written data is
already in the stdio buffer, the data may be completely safe!
</p> </p>
<p><strong></strong> <p><strong>I/O sentry ctor/dtor</strong> They can perform additional work
than the minimum required. I don't think we're currently taking
advantage of this yet.
</p>
<p><strong>[27.7.1.3]/16</strong>,<br>
<strong>[27.8.1.4]/10</strong>
The effects of <code>pubsetbuf/setbuf</code> are described
<a href="../27_io/howto.html#2">in this chapter</a>.
</p>
<p><strong>[27.8.1.4]/16</strong> Calling <code>fstream::sync</code> when
a get area exists will... whatever <code>fflush()</code> does, I think.
</p> </p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment