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

1 files changed, 115 insertions, 8 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: