c_io_stdio.h: Correct grammar in comments.

2001-11-02  Phil Edwards  <pme@gcc.gnu.org>

	* config/io/c_io_stdio.h:  Correct grammar in comments.
	* docs/doxygen/Intro.3:  Expand "top-level" man page.
	* docs/doxygen/doxygroups.cc:  New module definitions (comments).
	* docs/doxygen/mainpage.doxy:  Tweaks.
	* docs/doxygen/run_doxygen:  Update Doxygen version, massage man pages.

	Add @file hooks so that headers are considered to be documented.
	* include/bits/basic_ios.h, include/bits/basic_file.h,
	include/bits/basic_string.h, include/bits/boost_concept_check.h,
	include/bits/char_traits.h, include/bits/codecvt.h,
	include/bits/concept_check.h, include/bits/cpp_type_traits.h,
	include/bits/fpos.h, include/bits/gslice.h, include/bits/gslice_array.h,
	include/bits/indirect_array.h, include/bits/ios_base.h,
	include/bits/locale_facets.h, include/bits/localefwd.h,
	include/bits/mask_array.h, include/bits/pthread_allocimpl.h,
	include/bits/slice.h, include/bits/slice_array.h,
	include/bits/std_algorithm.h, include/bits/std_bitset.h,
	include/bits/std_complex.h, include/bits/std_deque.h,
	include/bits/std_fstream.h, include/bits/std_functional.h,
	include/bits/std_iomanip.h, include/bits/std_ios.h,
	include/bits/std_iosfwd.h, include/bits/std_iostream.h,
	include/bits/std_istream.h, include/bits/std_iterator.h,
	include/bits/std_limits.h, include/bits/std_list.h,
	include/bits/std_locale.h, include/bits/std_map.h,
	include/bits/std_memory.h, include/bits/std_numeric.h,
	include/bits/std_ostream.h, include/bits/std_queue.h,
	include/bits/std_set.h, include/bits/std_sstream.h,
	include/bits/std_stack.h, include/bits/std_streambuf.h,
	include/bits/std_string.h, include/bits/std_utility.h,
	include/bits/std_valarray.h, include/bits/std_vector.h,
	include/bits/stl_algo.h, include/bits/stl_alloc.h,
	include/bits/stl_bvector.h, include/bits/stl_construct.h,
	include/bits/stl_deque.h, include/bits/stl_heap.h,
	include/bits/stl_iterator.h, include/bits/stl_iterator_base_funcs.h,
	include/bits/stl_iterator_base_types.h, include/bits/stl_list.h,
	include/bits/stl_map.h, include/bits/stl_multimap.h,
	include/bits/stl_multiset.h, include/bits/stl_numeric.h,
	include/bits/stl_pair.h, include/bits/stl_pthread_alloc.h,
	include/bits/stl_queue.h, include/bits/stl_raw_storage_iter.h,
	include/bits/stl_relops.h, include/bits/stl_set.h,
	include/bits/stl_stack.h, include/bits/stl_tempbuf.h,
	include/bits/stl_threads.h, include/bits/stl_tree.h,
	include/bits/stl_uninitialized.h, include/bits/stl_vector.h,
	include/bits/stream_iterator.h, include/bits/streambuf_iterator.h,
	include/bits/stringfwd.h, include/bits/type_traits.h,
	include/bits/valarray_array.h, include/bits/valarray_meta.h:
	Add hooks, tweak comments only.

	* include/bits/stl_algobase.h (swap, min, iter_swap):  Also
	document these functions.
	* include/bits/stl_function.h:  Tweak link comments.

From-SVN: r46717

4 files changed, 204 insertions, 33 deletions

diff --git a/libstdc++-v3/docs/doxygen/Intro.3 b/libstdc++-v3/docs/doxygen/Intro.3
index 5df718b..6f4f3a5 100644
--- a/libstdc++-v3/docs/doxygen/Intro.3
+++ b/libstdc++-v3/docs/doxygen/Intro.3
@@ -1,15 +1,122 @@
+.\" t
 .\" This man page is released under the FDL as part of libstdc++-v3.
 .TH Intro 3 "27 September 2001" "GNU libstdc++-v3" "Standard C++ Library"
 .SH NAME
 Intro \- Introduction to the GNU libstdc++-v3 man pages
 .SH DESCRIPTION
-
-This should mention the man pages generated for modules.
-
+This man page serves as a brief introduction to the GNU implementation of
+the Standard C++ Library.  For a better introduction and more complete
+documentation, see the
+.B libstdc++-v3
+homepage listed at the end.
+.P
+All standard library entities are declared within
+.I namespace std
+and have manual entries beginning with "std_".  For example, to see
+documentation of the template class
+.I std::vector
+one would use "man std_vector".
+.P
+All the man pages are automatically generated by Doxygen.  For more
+information on this tool, see the HTML counterpart to these man pages.
+.P
+Some man pages do not correspond to individual classes or functions.  Rather
+they describe categories of the Standard Library.  (For a more thourough
+introduction to the various categories, consult a textbook such as Josuttis'
+or Austern's.)  These category pages are:
+.P
+.\" These are separated by ONE TAB.  Nothing else.  I don't like it either.
+.TS
+lB l.
+Arithmetic_functors	Functors for basic math.
+Assoc_containers	Key-based containers.
+Binder_functors	Functors which "remember" an argument.
+Comparison_functors	Functors wrapping built-in comparisons.
+Containers	An introduction to container classes.
+Func_ptr_functors	Functors for use with pointers to functions.
+Intro	This page.
+Intro_functors	An introduction to function objects, or functors.
+Logical_functors	Functors wrapping the Boolean operations.
+Member_ptr_functor	Functors for use with pointers to members.
+Namespace_Std	A listing of the contents of std::.
+Negation_functors	Functors which negate their contents.
+SGIextensions	A list of the extensions from the SGI STL subset.
+Sequences	Linear containers.
+.TE
+.P
+The HTML documentation goes into more depth.
 .SH FILES
-
-Lots.  Wish I knew enough *roff syntax to list them nicely.
-
+Lots!
+.SS Standard Headers
+These headers will be found automatically, unless you instruct the compiler
+otherwise.
+.TS
+lB lB lB lB.
+<algorithm>  <csignal>     <iomanip>   <ostream>
+<bitset>     <cstdarg>     <ios>       <queue>
+<cassert>    <cstddef>     <iosfwd>    <set>
+<cctype>     <cstdio>      <iostream>  <sstream>
+<cerrno>     <cstdlib>     <istream>   <stack>
+<cfloat>     <cstring>     <iterator>  <stdexcept>
+<ciso>646    <ctime>       <limits>    <streambuf>
+<climits>    <cwchar>      <list>      <string>
+<clocale>    <cwctype>     <locale>    <utility>
+<cmath>      <deque>       <map>       <valarray>
+<complex>    <fstream>     <memory>    <vector>
+<csetjmp>    <functional>  <numeric>
+.TE
+.SS Backwards-Compatability Headers
+For GCC 3.0 these headers will be found automatically, unless you instruct
+the compiler otherwise.  You should not depend on this, instead you should
+read FAQ 5.4 and use a
+.B backward/
+prefix.
+.TS
+lB lB lB lB.
+<algo.h>      <hash_map.h>   <map.h>       <slist.h>
+<algobase.h>  <hash_set.h>   <multimap.h>  <stack.h>
+<alloc.h>     <hashtable.h>  <multiset.h>  <stream.h>
+<bvector.h>   <heap.h>       <new.h>       <streambuf.h>
+<complex.h>   <iomanip.h>    <ostream.h>   <strstream>
+<defalloc.h>  <iostream.h>   <pair.h>      <strstream.h>
+<deque.h>     <istream.h>    <queue.h>     <tempbuf.h>
+<fstream.h>   <iterator.h>   <rope.h>      <tree.h>
+<function.h>  <list.h>       <set.h>       <vector.h>
+.TE
+.SS Extension Headers
+These headers will only be found automatically if you include the leading
+.B ext/
+in the name.  Otherwise you need to read FAQ 5.4.
+.TS
+lB.
+<ext/hash_map>
+<ext/hash_set>
+<ext/rope>
+<ext/slist>
+.TE
+.SS Libraries
+.TP
+.I libstdc++.a
+The library implementation in static archive form.  If you did not configure
+libstdc++-v3 to use shared libraries, this will always be used.  Otherwise
+it will only be used if the user requests it.
+.TP
+.I libsupc++.a
+This library contains C++ language support routines.  Usually you will never
+need to know about it, but it can be useful.  See FAQ 2.5.
+.TP
+.I libstdc++.so[.N]
+The library implementation in shared object form.  This will be used in
+preference to the static archive form by default.  Currently N will either
+start with 3 or with 4, but your system vendor may change the name as they
+see fit.  If N is in the 2.x series, then you are looking at the old
+libstdc++-v2 library, which we do not maintain.
+.TP
+.I libstdc++.la
+.TP
+.I libsupc++.la
+These are Libtool library files, and should only be used when working with
+that tool.
 .SH CONFORMING TO
 Almost conforming to
 .BI "International Standard ISO/IEC 14882:1998(E), " "Programming Languages --- C++"
@@ -20,5 +127,5 @@ Working Group,
 .UR
 http://gcc.gnu.org/libstdc++/
 .UE
-for the Frequently Asked Questions, online documentation, and more.
-
+for the Frequently Asked Questions, online documentation, and much, much more!
+.\" vim:ts=8:noet:
diff --git a/libstdc++-v3/docs/doxygen/doxygroups.cc b/libstdc++-v3/docs/doxygen/doxygroups.cc
index b74bab1..72e5ef3 100644
--- a/libstdc++-v3/docs/doxygen/doxygroups.cc
+++ b/libstdc++-v3/docs/doxygen/doxygroups.cc
@@ -3,22 +3,83 @@
 // source headers themselves.  It is a ".cc" file for the sole cheesy reason
 // that it triggers many different text editors into doing Nice Things when
 // typing comments.  However, it is mentioned nowhere except the *cfg.in files.
+// Pieces separated by '// //' lines will usually not be presented to the
+// user on the same page.
 
-/** @addtogroup SGIextensions
- *
- *  Because libstdc++-v3 based its implementation of the STL subsections of
- *  the library on the SGI 3.3 implementation, we inherited their extensions
- *  as well.
- *
- *  They are additionally documented in the
- *  <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">
- *  online documentation</a>, a copy of which is also shipped with the
- *  library source code (in .../docs/html/documentation.html).  You can also
- *  read the documentation <a href="http://www.sgi.com/tech/stl/">on SGI's
- *  site</a>, which is still running even though the code is not maintained.
- *
- *  <strong>NB</strong> that the following notes are pulled from various
- *  comments all over the place, so they may seem stilted.
- *  <hr>
+// // // // // // // // // // // // // // // // // // // // // // // //
+/** @addtogroup SGIextensions STL extensions from SGI
+Because libstdc++-v3 based its implementation of the STL subsections of
+the library on the SGI 3.3 implementation, we inherited their extensions
+as well.
+
+They are additionally documented in the
+<a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">
+online documentation</a>, a copy of which is also shipped with the
+library source code (in .../docs/html/documentation.html).  You can also
+read the documentation <a href="http://www.sgi.com/tech/stl/">on SGI's
+site</a>, which is still running even though the code is not maintained.
+
+<strong>NB</strong> that the following notes are pulled from various
+comments all over the place, so they may seem stilted.
+<hr>
+*/
+
+// // // // // // // // // // // // // // // // // // // // // // // //
+// This is standalone because, unlike the functor introduction, there is no
+// single header file which serves as a base "all containers must include
+// this header".  We do some quoting of 14882 here.
+/** @addtogroup Containers Containers
+Containers are collections of objects.
+
+A container may hold any type which meets certain requirements, but the type
+of contained object is chosen at compile time, and all objects in a given
+container must be of the same type.  (Polymorphism is possible by declaring a
+container of pointers to a base class and then populating it with pointers to
+instances of derived classes.  Variant value types such as the @c any class
+from <a href="http://www.boost.org/">Boost</a> can also be used.
+
+All contained types must be @c Assignable and @c CopyConstructible.
+Specific containers may place additional requirements on the types of
+their contained objects.
+
+Containers manage memory allocation and deallocation themselves when
+storing your objects.  The objects are destroyed when the container is
+itself destroyed.  Note that if you are storing pointers in a container,
+@c delete is @e not automatically called on the pointers before destroying them.
+
+All containers must meet certain requirements.  They would be listed here
+except I'm not certain how much of 14882 can be reproduced without a
+copyright violation.  Reproducing Tables 65 through 69 is a lot of typing...
+
+The standard containers are further refined into
+@link Sequences Sequences@endlink and
+@link Assoc_containers Associative Containers@endlink.
 */
 
+/** @addtogroup Sequences Sequences
+Sequences arrange a collection of objects into a strictly linear order.
+
+The differences between sequences are usually due to one or both of the
+following:
+  - memory management
+  - algorithmic complexity
+
+As an example of the first case, @c vector is required to use a contiguous
+memory layout, while other sequences such as @c deque are not.
+
+The prime reason for chosing one sequence over another should be based on
+the second category of differences, algorithmic complexity.  For example, if
+you need to perform many inserts and removals from the middle of a sequence,
+@c list would be ideal.  But if you need to perform constant-time access to
+random elements of the sequence, then @c list should not be used.
+*/
+
+/** @addtogroup Assoc_containers Associative Containers
+Associative containers allow fast retrieval of data based on keys.
+
+Each container type is parameterized on a @c Key type, and an ordering
+relation used to sort the elements of the container.
+*/
+
+// // // // // // // // // // // // // // // // // // // // // // // //
+
diff --git a/libstdc++-v3/docs/doxygen/mainpage.doxy b/libstdc++-v3/docs/doxygen/mainpage.doxy
index f1fa54d..467f5ff 100644
--- a/libstdc++-v3/docs/doxygen/mainpage.doxy
+++ b/libstdc++-v3/docs/doxygen/mainpage.doxy
@@ -17,13 +17,14 @@
     <li><a href="annotated.html">Compound List</a>
     <li><a href="classes.html">Alphabetical List</a>
     <li><a href="files.html">File List</a>
-    <!-- Will be useful, but not yet. <li><a href="modules.html">Modules</a> -->
+    <li><a href="modules.html">Modules</a>
    </ul>
 </p>
 
 <h2> Generating this file </h2>
-<p>This page is automatically generated.  The Makefile rule <code> make
-   doxygen </code> in the libstdc++-v3 build directory generates these pages
+<p>These HTML pages are automatically generated, along with the man pages.
+   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>.
diff --git a/libstdc++-v3/docs/doxygen/run_doxygen b/libstdc++-v3/docs/doxygen/run_doxygen
index d515dfd..4563f92 100644
--- a/libstdc++-v3/docs/doxygen/run_doxygen
+++ b/libstdc++-v3/docs/doxygen/run_doxygen
@@ -8,7 +8,7 @@
 
 
 # We can check now that the version of doxygen is >= this variable.
-DOXYVER=1.2.6
+DOXYVER=1.2.10
 doxygen=
 
 find_doxygen() {
@@ -126,14 +126,11 @@ chmod u+w $outdir
 # man pages for doxygen modules need to be renamed (or deleted).  And the
 # generated #include lines need to be changed from the internal names to the
 # standard ones (e.g., "#include <stl_tempbuf.h>" -> "#include <memory>").
-#
-# File names with embedded spaces (EVIL!) need to be....?  renamed or removed?
 cd $outdir/man/man3 && {
 echo :: Fixing up the man pages...
 
-# requires GNU tools
-find . -name "* *" -print0 | xargs -0 rm
-rm *.h.3
+# File names with embedded spaces (EVIL!) need to be....?  renamed or removed?
+find . -name "* *" -print0 | xargs -0 rm        # requires GNU tools
 
 # can leave SGIextensions.3 alone, it's an okay name
 mv s20_3_1_base.3           Intro_functors.3
@@ -144,6 +141,11 @@ mv s20_3_5_negators.3       Negation_functors.3
 mv s20_3_6_binder.3         Binder_functors.3
 mv s20_3_7_adaptors.3       Func_ptr_functors.3
 mv s20_3_8_memadaptors.3    Member_ptr_functors.3
+mv std.3                    Namespace_Std.3
+
+# man pages are for functions/types/other entities, not source files directly
+find . -name "[a-z]*" -a ! -name "std_*" -print | xargs rm
+rm -f *.h.3 *config* *.cc.3 *.tcc.3
 
 # Standardize the displayed header names.  If anyone who knows perl cares
 # enough to rewrite all this, feel free.  This only gets run once a century,