Skip to content

R
riscv-gcc-1
Commit fd58f127 by Phil Edwards
Options

[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
Showing with 207 additions and 27 deletions
libstdc++-v3/ChangeLog
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>
libstdc++/5579
......
libstdc++-v3/docs/doxygen/TODO
......@@ -30,13 +30,6 @@ ext/* Some of the SGI algorithm/functional extensions.
__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:
......
libstdc++-v3/docs/doxygen/mainpage.doxy → libstdc++-v3/docs/doxygen/mainpage.html
/*! \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>
<p class="smallertext">Generated 2002-02-04.</p>
<p>There are two types of documentation for libstdc++-v3. One is the
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>
......@@ -26,8 +51,12 @@
The Makefile rule <code> 'make
doxygen' </code> in the libstdc++-v3 build directory generates these pages
using a tool called, appropriately enough, Doxygen. To learn more about
Doxygen, take a look at <a href="http://www.doxygen.org">the Doxygen
webpage</a>.
Doxygen, take a look at
<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>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>.
</ul>
</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>
libstdc++-v3/docs/doxygen/run_doxygen
......@@ -146,6 +146,7 @@ set -e
set +e
test $do_html = yes && {
cp ${srcdir}/docs/doxygen/mainpage.html ${outdir}/html_${mode}/index.html
echo ::
echo :: HTML pages begin with
echo :: ${outdir}/html_${mode}/index.html
......
libstdc++-v3/docs/doxygen/style.css
......@@ -21,3 +21,4 @@ FONT.comment { color: #800000 }
FONT.preprocessor { color: #806020 }
FONT.stringliteral { color: #002080 }
FONT.charliteral { color: #008080 }
.smallertext { font-size: smaller }
libstdc++-v3/docs/doxygen/user.cfg.in
......@@ -296,8 +296,7 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
INPUT = @srcdir@/docs/doxygen/mainpage.doxy \
@srcdir@/docs/doxygen/doxygroups.cc \
INPUT = @srcdir@/docs/doxygen/doxygroups.cc \
@srcdir@/src \
@srcdir@/libsupc++/exception \
@srcdir@/libsupc++/new \
......
libstdc++-v3/docs/html/17_intro/howto.html
......@@ -165,7 +165,7 @@
<hr>
<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>
<dt><code>[1.3.5] implementation-defined behavior</code>
<dd>behavior, for a well-formed program construct and correct data, that
......@@ -174,10 +174,12 @@
</dl></blockquote>
We do so here, for the C++ library only. Behavior of the compiler,
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>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><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best
discussed in the various sections on multithreading (see above).
......@@ -200,27 +202,66 @@
<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? -->
class. But they are the <em>mangled</em> names; you will need to call
<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
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.)
</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><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><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><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><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><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><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><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>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
......
libstdc++-v3/include/std/std_fstream.h
......@@ -237,7 +237,11 @@ namespace std
};
// 27.8.1.5 Template class basic_ifstream
/**
* Derivation of general input streams, specific to files.
*/
template<typename _CharT, typename _Traits>
class basic_ifstream : public basic_istream<_CharT, _Traits>
{
......@@ -258,10 +262,19 @@ namespace std
public:
// Constructors/Destructors:
/** Default constructor. Create an input file stream. */
basic_ifstream()
: __istream_type(NULL), _M_filebuf()
{ this->init(&_M_filebuf); }
/**
* @brief Create an input file stream.
* @param s Null terminated string specifying filename.
* @param mode Open file in specified mode (see std::ios_base).
*
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
*/
explicit
basic_ifstream(const char* __s, ios_base::openmode __mode = ios_base::in)
: __istream_type(NULL), _M_filebuf()
......@@ -274,6 +287,10 @@ namespace std
{ }
// Members:
/**
* @brief Get a pointer to the file stream's buffer.
* @return Pointer to basic_filebuf.
*/
__filebuf_type*
rdbuf() const
{ return const_cast<__filebuf_type*>(&_M_filebuf); }
......@@ -288,6 +305,7 @@ namespace std
this->setstate(ios_base::failbit);
}
/** Close the file. */
void
close(void)
{
......@@ -298,6 +316,9 @@ namespace std
// 27.8.1.8 Template class basic_ofstream
/**
* Derivation of general output streams, specific to files.
*/
template<typename _CharT, typename _Traits>
class basic_ofstream : public basic_ostream<_CharT,_Traits>
{
......@@ -318,10 +339,19 @@ namespace std
public:
// Constructors:
/** Default constructor for output file_stream. */
basic_ofstream()
: __ostream_type(NULL), _M_filebuf()
{ this->init(&_M_filebuf); }
/**
* @brief Create an output stream.
* @param s Null terminated string specifying filename.
* @param mode Open file in specified mode (see std::ios_base).
*
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
*/
explicit
basic_ofstream(const char* __s,
ios_base::openmode __mode = ios_base::out|ios_base::trunc)
......@@ -335,13 +365,29 @@ namespace std
{ }
// Members:
/**
* @brief Get a pointer to the file stream's buffer.
* @return Pointer to basic_filebuf.
*/
__filebuf_type*
rdbuf(void) const
{ return const_cast<__filebuf_type*>(&_M_filebuf); }
/**
* @brief Query to see if file stream is open.
* @return True if stream is open.
*/
bool
is_open(void) { return _M_filebuf.is_open(); }
/**
* @brief Specify a file to open for output.
* @param s Null terminated string specifying filename.
* @param mode Mode in which to open file (see std::ios_base).
*
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
*/
void
open(const char* __s,
ios_base::openmode __mode = ios_base::out | ios_base::trunc)
......@@ -350,6 +396,7 @@ namespace std
this->setstate(ios_base::failbit);
}
/** Close the file stream. */
void
close(void)
{
......@@ -360,6 +407,9 @@ namespace std
// 27.8.1.11 Template class basic_fstream
/**
* Derivation of general input/output streams, specific to files.
*/
template<typename _CharT, typename _Traits>
class basic_fstream : public basic_iostream<_CharT, _Traits>
{
......@@ -381,10 +431,19 @@ namespace std
public:
// Constructors/destructor:
/** Default constructor. Create a file stream. */
basic_fstream()
: __iostream_type(NULL), _M_filebuf()
{ this->init(&_M_filebuf); }
/**
* @brief Create an input/output stream.
* @param s Null terminated string specifying filename.
* @param mode Open file in specified mode (see std::ios_base).
*
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
*/
explicit
basic_fstream(const char* __s,
ios_base::openmode __mode = ios_base::in | ios_base::out)
......@@ -398,13 +457,29 @@ namespace std
{ }
// Members:
/**
* @brief Get a pointer to the file stream's buffer.
* @return Pointer to basic_filebuf.
*/
__filebuf_type*
rdbuf(void) const
{ return const_cast<__filebuf_type*>(&_M_filebuf); }
/**
* @brief Query to see if file stream is open.
* @return True if stream is open.
*/
bool
is_open(void) { return _M_filebuf.is_open(); }
/**
* @brief Specify a file to open for input and/or output.
* @param s Null terminated string specifying filename.
* @param mode Mode in which to open file (see std::ios_base).
*
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
*/
void
open(const char* __s,
ios_base::openmode __mode = ios_base::in | ios_base::out)
......@@ -413,6 +488,7 @@ namespace std
setstate(ios_base::failbit);
}
/** Close the file stream. */
void
close(void)
{
......
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