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

	* docs/doxygen/TODO:  Update.
	* docs/doxygen/doxygroups.cc:  Tweak __gnu_cxx description.
	* docs/doxygen/mainpage.html:  Add TODO list link.
	* docs/doxygen/user.cfg.in:  Add @doctodo hook.
	* docs/doxygen/tables.html:  New file, emoty structure only.

	* include/bits/stl_iterator.h:  Doxygenate just about everything.
	* include/bits/stl_iterator_base_funcs.h:  Ditto, clean up spaces.
	* include/bits/stl_iterator_base_types.h:  Add notes.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@49608 138bc75d-0d04-0410-961f-82ee72b054a4

5 files changed, 283 insertions, 11 deletions

diff --git a/libstdc++-v3/docs/doxygen/TODO b/libstdc++-v3/docs/doxygen/TODO
index da2f25ab5e7..375cd5fc785 100644
--- a/libstdc++-v3/docs/doxygen/TODO
+++ b/libstdc++-v3/docs/doxygen/TODO
@@ -7,6 +7,13 @@ documented in the course of doing other headers.
 "Untouched" means I've deliberately skipped it for various reasons, or
 haven't gotten to it yet.  It /will/ be done (by somebody, eventually.)
 
+If you document an area and need to skip (for whatever reason) a non-trivial
+entity (i.e., one that should be documented), go ahead and add the comment
+markup, and use the homegrown @doctodo tag.  See include/bits/stl_iterator.h
+for examples of this.  Doing so will at least cause doxygen to consider the
+entitiy as documented and include it in the output.  It will also add the
+entity to the generated TODO page.
+
 
  Area           Still needs to be doxygen-documented
 -----------------------------------------------------------
@@ -18,7 +25,8 @@ c20             Note A
 c21             Untouched, Note B
 c22             Untouched
 c23             See doxygroups.cc and Note B.
-c24             Untouched
+c24             stl_iterator.h (__normal_iterator, other small TODO bits)
+                stream iterators
 c25             stl_algo.h (lots of stuff)
 c26             <complex>, <valarray>, stl_numeric.h[26.4], Note A
 c27             Untouched
@@ -40,8 +48,7 @@ do not have the C code (to which the doxygen comments would be attached),
 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?  I suspect we should
-simply write some HTML tables (say, one <table> per Table per file), and
+in the standard.  These are being pseudo-duplicated in tables.html.  We can
 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.
diff --git a/libstdc++-v3/docs/doxygen/doxygroups.cc b/libstdc++-v3/docs/doxygen/doxygroups.cc
index d2bda88f8ec..8af04b1ea54 100644
--- a/libstdc++-v3/docs/doxygen/doxygroups.cc
+++ b/libstdc++-v3/docs/doxygen/doxygroups.cc
@@ -13,14 +13,17 @@
  *  @brief Everything defined by the ISO C++ Standard is within namespace std.
 */
 /** @namespace __gnu_cxx
- *  @brief Non-standard things.
+ *  @brief This namespace serves two purposes.
  *
- *  This namespace is used for
+ *  This namespace is used for two things:
  *  -  sequestering internal (implementation-only) names away from the
- *     global namespace
- *  -  GNU extensions
+ *     global namespace; these are details of the implementation and should
+ *     not be touched by users
+ *  -  GNU extensions for public use
  *
- *  This is still fluid and changing rapidly.
+ *  This is still fluid and changing rapidly.  Currently the rule is:  if an
+ *  entitity is found in the user-level documentation, it falls into the
+ *  second category.
 */
 
 // // // // // // // // // // // // // // // // // // // // // // // //
diff --git a/libstdc++-v3/docs/doxygen/mainpage.html b/libstdc++-v3/docs/doxygen/mainpage.html
index d7b1c436d29..88ea279331f 100644
--- a/libstdc++-v3/docs/doxygen/mainpage.html
+++ b/libstdc++-v3/docs/doxygen/mainpage.html
@@ -25,7 +25,7 @@
 
 <h2> Documentation Overview </h2>
 
-<p class="smallertext">Generated 2002-02-04.</p>
+<p class="smallertext">Generated 2002-02-08.</p>
 
 <p>There are two types of documentation for libstdc++-v3.  One is the
    distribution documentation, which can be read online at
@@ -97,6 +97,7 @@ href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
     <li><a href="namespacemembers.html">Namespace Members</a>
     <li><a href="functions.html">Compound Members</a>
     <li><a href="globals.html">File Members</a>
+    <li><a href="todo.html">TODO List</a> (This is incomplete... how ironic.)
    </ul>
 </p>
 
diff --git a/libstdc++-v3/docs/doxygen/tables.html b/libstdc++-v3/docs/doxygen/tables.html
new file mode 100644
index 00000000000..d38e461c537
--- /dev/null
+++ b/libstdc++-v3/docs/doxygen/tables.html
@@ -0,0 +1,260 @@
+<!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>Tables</title>
+<link href="style.css" rel="stylesheet" type="text/css">
+</head>
+
+<body bgcolor="#ffffff">
+<!--
+     Tables can be jumped to with their number, e.g., "tables.html#67".
+-->
+
+<h1>Tables</h1>
+
+<p>Most of the requirements on containers are presented in the ISO standard
+   in the form of tables.  In order to avoid massive duplication of effort,
+   we follow the standard's lead and present the information here.
+   Individual classes will only document their departures from these tables
+   (removed functions, additional functions, changes, etc).
+</p>
+
+<p>The numbers are the same as those used in the standard.
+</p>
+
+<hr />
+
+<a name="65"><p>
+<table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
+       cols="3" title="Table 65">
+<caption><h2>Table 65 --- Container Requirements</h2></caption>
+<tr><th colspan="4">
+Anything calling itself a container must meet these minimum requirements.
+</th></tr>
+<tr>
+<td><strong>expression</strong></td>
+<td><strong>result type</strong></td>
+<td><strong>notes</strong></td>
+<td><strong>complexity</strong></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+</table title="Table 65"></p></a>
+
+
+<a name="66"><p>
+<table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
+       cols="3" title="Table 66">
+<caption><h2>Table 66 --- Reversible Container Requirements</h2></caption>
+<tr><th colspan="4">
+If a container's iterator is bidirectional or random-access, then the
+container also meets these requirements.
+Foo, bar, and baz are such containers.
+</th></tr>
+<tr>
+<td><strong>expression</strong></td>
+<td><strong>result type</strong></td>
+<td><strong>notes</strong></td>
+<td><strong>complexity</strong></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+</table title="Table 66"></p></a>
+
+
+<a name="67"><p>
+<table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
+       cols="3" title="Table 67">
+<caption><h2>Table 67 --- Sequence Requirements</h2></caption>
+<tr><th colspan="4">
+These are in addition to the requirements of <a href="#65">containers</a>.
+Foo, bar, and baz are such containers.
+</th></tr>
+<tr>
+<td><strong>expression</strong></td>
+<td><strong>result type</strong></td>
+<td><strong>notes</strong></td>
+<td><strong>complexity</strong></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+</table title="Table 67"></p></a>
+
+
+<a name="68"><p>
+<table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
+       cols="3" title="Table 68">
+<caption><h2>Table 68 --- Optional Sequence Operations</h2></caption>
+<tr><th colspan="4">
+These operations are only included in containers when the operation can be
+done in constant time.
+Foo, bar, and baz are such containers.
+</th></tr>
+<tr>
+<td><strong>expression</strong></td>
+<td><strong>result type</strong></td>
+<td><strong>notes</strong></td>
+<td><strong>complexity</strong></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+</table title="Table 68"></p></a>
+
+
+<a name="69"><p>
+<table cellpadding="3" cellspacing="5" align="center" rules="rows" border="3"
+       cols="3" title="Table 69">
+<caption><h2>Table 69 --- Associative Container Requirements</h2></caption>
+<tr><th colspan="4">
+These are in addition to the requirements of <a href="#65">containers</a>.
+</th></tr>
+<tr>
+<td><strong>expression</strong></td>
+<td><strong>result type</strong></td>
+<td><strong>notes</strong></td>
+<td><strong>complexity</strong></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+
+<tr>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+</table title="Table 69"></p></a>
+
+
+<hr />
+<p class="smallertext"><em>
+See <a href="mainpage.html">mainpage.html</a> for copying conditions.
+</em></p>
+
+
+</body>
+</html>
+
diff --git a/libstdc++-v3/docs/doxygen/user.cfg.in b/libstdc++-v3/docs/doxygen/user.cfg.in
index 430194b5579..2a1a4c639f2 100644
--- a/libstdc++-v3/docs/doxygen/user.cfg.in
+++ b/libstdc++-v3/docs/doxygen/user.cfg.in
@@ -201,7 +201,7 @@ TAB_SIZE               = 4
 # disable (NO) the todo list. This list is created by putting \todo 
 # commands in the documentation.
 
-GENERATE_TODOLIST      = NO
+GENERATE_TODOLIST      = YES
 
 # The GENERATE_TESTLIST tag can be used to enable (YES) or 
 # disable (NO) the test list. This list is created by putting \test 
@@ -223,7 +223,8 @@ GENERATE_BUGLIST       = YES
 # You can put \n's in the value part of an alias to insert newlines.
 
 ALIASES                = "maint=@if maint" \
-                         "endmaint=@endif"
+                         "endmaint=@endif" \
+	"doctodo=@todo\nDoc me!  See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more."
 
 # The ENABLED_SECTIONS tag can be used to enable conditional 
 # documentation sections, marked by \if sectionname ... \endif.