*: Add Doxygen hooks.

2001-09-27  Phil Edwards  <pme@gcc.gnu.org>

	* include/std/*:  Add Doxygen hooks.
	* docs/doxygen/Intro.3:  New file, general intro to the man pages.
	* docs/doxygen/mainpage.doxy:  Formatting tweaks.  List our own links
	rather than using a generated index.
	* docs/doxygen/user.cfg.in:  Disable the index, enable man pages.
	* docs/doxygen/run_doxygen:  Massage the generated man pages, using...
	* docs/doxygen/stdheader.cc:  ...this new file.

From-SVN: r45850

libstdc++-v3/ChangeLog

@@ -1,3 +1,13 @@
+2001-09-27  Phil Edwards  <pme@gcc.gnu.org>
+
+	* include/std/*:  Add Doxygen hooks.
+	* docs/doxygen/Intro.3:  New file, general intro to the man pages.
+	* docs/doxygen/mainpage.doxy:  Formatting tweaks.  List our own links
+	rather than using a generated index.
+	* docs/doxygen/user.cfg.in:  Disable the index, enable man pages.
+	* docs/doxygen/run_doxygen:  Massage the generated man pages, using...
+	* docs/doxygen/stdheader.cc:  ...this new file.
+
 2001-09-26  Stan Shebs  <shebs@apple.com>
 
 	* include/Makefile.am: Remove RCS Id strings.

libstdc++-v3/docs/doxygen/Intro.3

@@ -0,0 +1,24 @@
+.\" 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.
+
+.SH FILES
+
+Lots.  Wish I knew enough *roff syntax to list them nicely.
+
+.SH CONFORMING TO
+Almost conforming to
+.BI "International Standard ISO/IEC 14882:1998(E), " "Programming Languages --- C++"
+(aka the C++ standard), in addition to corrections proposed by the Library
+Working Group,
+.SM JTC1/SC22/WG21.
+.SH SEE ALSO
+.UR
+http://gcc.gnu.org/libstdc++/
+.UE
+for the Frequently Asked Questions, online documentation, and more.
+

libstdc++-v3/docs/doxygen/mainpage.doxy

@@ -1,62 +1,75 @@
 /*! \mainpage
 
-<h2> documentation overview </h2>
+<h2> Documentation Overview </h2>
 
-<p>
+<p>There are two types of documentation for libstdc++-v3.  One is the
-There are two types of documentation for libstdc++-v3. One is the distribution documentation, which can be read
+   distribution documentation, which can be read online at
-<a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">here</a>.
+   <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html</a>
+   or offline from docs/html/documentation.html in the library source
+   directory.
 </p>
 
-<p>
+<p>The other type is the source documentation, of which this is the first page.
-The other is the source documentation, of which this is the first page.
+   Here are quick links to the pages which we seem to use the most; a full
+   index is at the bottom:
+   <!-- Keep this in sync with below. -->
+   <ul>
+    <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> -->
+   </ul>
 </p>
 
-<h2> generating this file </h2>
+<h2> Generating this file </h2>
-<p>
+<p>This page is automatically generated.  The Makefile rule <code> make
-This page is automatically generated. The Makefile rule <tt>make
+   doxygen </code> in the libstdc++-v3 build directory generates these pages
-doxygen</tt> 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
+   Doxygen, take a look at <a href="http://www.doxygen.org">the Doxygen
-about doxygen, take a look at <a href="http://www.doxygen.org"> the
+   webpage</a>.
-doxygen webpage </a>.
 </p>
 
-<p>
+<p>The libstdc++-v3 configuration files needed to generate doxygen output
-The libstdc++-v3 configuration files needed to generate doxygen output
+   are located:
-are located:
+   <ul><li><code>docs/doxygen/user.cfg.in</code>
-<p> <tt> docs/doxygen/user.cfg.in</tt> </p>
+       <li><code>docs/doxygen/maint.cfg.in</code>
-<p> <tt> docs/doxygen/maint.cfg.in</tt> </p>
+   </ul>
 </p>
 
 <h2> libstdc++-v3 doxygen style guide </h2>
-<p>
+<p>In general, libstdc++-v3 files should be formatted according to the
-In general, libstdc++-v3 files should be formatted according to the
+   GNU C++ Coding Standard rules found in the file <a
-GNU C++ Coding Standard rules found in the file <a
 href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
-Before any doxygen-specific formatting tweaks are made, please try to
+   Before any doxygen-specific formatting tweaks are made, please try to
-make sure that the initial formatting is sound.
+   make sure that the initial formatting is sound.
 </p>
 
-<p>
+<p>The formatting guidelines for using libstdc++-v3 with doxygen are still
-The formatting guidelines for using libstdc++-v3 with doxygen are
+   incomplete.  There seems to be a marginal preference for the use of
-still incomplete. There seems to be a marginal preference for the use
+   Java-Doc style formatting, with the idea that the single-line style
-of Java-Doc style formatting, with the idea that the single-line style
+   (triple-slash) is the least intrusive mechanism for getting libstdc++-v3
-(triple-slash) is the least intrusive mechanism for getting
+   documented and cross-referenced while at the same time minimizing
-libstdc++-v3 documented and cross-referenced while at the same time
+   disruption to the current formatting.  Full documentation of functions
-minimizing disruption to the current formatting.
+   (parameter types, return values, etc) will require the slash-splat-splat
+   &quot;extended C&quot; commenting style.
 </p>
 
-<p>
+<h2> Full page index </h2>
-For the time being, please see <tt>include/bits/char_traits.h</tt>
+<p>Here are entry points to all the pages generated by Doxygen:
-which is the test bed for a finished doxygen style guide.
+   <ul>
+    <li><a href="index.html">Main Page</a>
+    <li><a href="modules.html">Modules</a>
+    <li><a href="namespaces.html">Namespace List</a>
+    <li><a href="hierarchy.html">Class Hierarchy</a>
+    <li><a href="classes.html">Alphabetical List</a>
+    <li><a href="annotated.html">Compound List</a>
+    <li><a href="files.html">File List</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>
+   </ul>
 </p>
 
 */
 
 
-
-
-
-
-
-
-

libstdc++-v3/docs/doxygen/run_doxygen

@@ -1,6 +1,6 @@
 #!/bin/sh
 
-# Runs doxygen.  Possibly will massage the output files.
+# Runs doxygen and massages the output files.
 #
 # Synopsis:  run_doxygen --mode=[user|maint]  v3srcdir  v3builddir
 #
@@ -69,14 +69,6 @@ parse_options() {
         mode=$arg ;;
       --mode | --help | -h)
         print_usage ;;
-      --version | -v)
-        # Aw, that's so cuuuute... don't ask, I needed it.
-        blank=
-        Id=is
-        echo You expect this dinky script to track a version?  Okay, here
-        echo it $Id: run_doxygen,v 1.6 2001/07/11 19:35:47 pme Exp $blank
-        exit 0
-        ;;
       *)
         # this turned out to be a mess, maybe change to --srcdir=, etc
         if test $srcdir = unset; then
@@ -129,12 +121,56 @@ chmod u+w $outdir
   echo :: Finished, exit code was $?
 )
 
-# mess with output files here?
+# Mess with the man pages.  We don't need documentation of the internal
+# headers, since the man pages for those contain nothing useful anyhow.  The
+# 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
+
+# can leave SGIextensions.3 alone, it's an okay name
+mv s20_3_1_base.3           Intro_functors.3
+mv s20_3_2_arithmetic.3     Arithmetic_functors.3
+mv s20_3_3_comparisons.3    Comparison_functors.3
+mv s20_3_4_logical.3        Logical_functors.3
+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
+
+# 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,
+# and I'm off getting coffee then anyhow, so I didn't care enough to make
+# this super-fast.
+g++ ${srcdir}/docs/doxygen/stdheader.cc -o ./stdheader
+problematic=`egrep -l '#include <.*_.*>' [a-z]*.3`
+for f in $problematic; do
+    # this is also slow, but safe and easy to debug
+    oldh=`sed -n '/#include </s/.*<\(.*\)>.*/\1/p' $f`
+    newh=`echo $oldh | ./stdheader`
+    sed "s=${oldh}=${newh}=" $f > TEMP
+    mv TEMP $f
+done
+rm stdheader
+
+cp ${srcdir}/docs/doxygen/Intro.3 .
+
+}
+
+# all done
 echo ::
 echo :: Doxygen output begins with
 echo :: ${outdir}/html_${mode}/index.html
 echo ::
+echo :: Man pages in ${outdir}/man
+echo ::
 
 exit 0
 

libstdc++-v3/docs/doxygen/stdheader.cc

@@ -0,0 +1,146 @@
+// This is a slow larval-stage kludge to help massage the generated man
+// pages.  It's used like this:
+const char* const usage = 
+"\nTakes on stdin, whitespace-separated words of the form\n"
+"\n"
+"    [bits/]stl_foo.h\n"
+"    [bits/]std_foo.h\n"
+"\n"
+"and writes on stdout the nearest matching standard header name.\n"
+"\n"
+"Takes no command-line arguments.\n"
+"\n";
+
+#include <string>
+#include <map>
+#include <iostream>
+
+typedef std::map<std::string, std::string>   Map;
+
+Map  headers;
+
+void init_map()
+{
+    // Enter the glamourous world of data entry!!  Maintain these!
+    headers["algo.h"]                   = "algorithm";
+    headers["algobase.h"]               = "algorithm";
+    headers["algorithm.h"]              = "algorithm";
+    headers["alloc.h"]                  = "memory";
+    headers["basic_ios.h"]              = "ios";
+    headers["basic_ios.tcc"]            = "ios";
+    headers["basic_string.h"]           = "string";
+    headers["basic_string.tcc"]         = "string";
+    headers["bitset.h"]                 = "bitset";
+    headers["bvector.h"]                = "vector";
+    //headers["char_traits.h"]            uhhhhhh
+    headers["complex.h"]                = "complex";
+    //headers["construct.h"]              stl_construct.h entirely internal
+    headers["deque.h"]                  = "deque";
+    headers["fstream.h"]                = "fstream";
+    headers["fstream.tcc"]              = "fstream";
+    headers["function.h"]               = "functional";
+    headers["functional.h"]             = "functional";
+    headers["heap.h"]                   = "algorithm";
+    headers["iomanip.h"]                = "iomanip";
+    headers["ios.h"]                    = "ios";
+    headers["iosfwd.h"]                 = "iosfwd";
+    headers["iostream.h"]               = "iostream";
+    headers["istream.h"]                = "istream";
+    headers["istream.tcc"]              = "istream";
+    headers["iterator.h"]               = "iterator";
+    headers["iterator_base_funcs.h"]    = "iterator";
+    headers["iterator_base_types.h"]    = "iterator";
+    headers["limits.h"]                 = "limits";
+    headers["list.h"]                   = "list";
+    headers["locale.h"]                 = "locale";
+    headers["locale_facets.h"]          = "locale";
+    headers["locale_facets.tcc"]        = "locale";
+    headers["map.h"]                    = "map";
+    headers["memory.h"]                 = "memory";
+    headers["multimap.h"]               = "map";
+    headers["multiset.h"]               = "set";
+    headers["numeric.h"]                = "numeric";
+    headers["ostream.h"]                = "ostream";
+    headers["ostream.tcc"]              = "ostream";
+    headers["pair.h"]                   = "utility";
+    //headers["pthread_alloc.h"]          who knows
+    headers["queue.h"]                  = "queue";
+    headers["raw_storage_iter.h"]       = "memory";
+    headers["relops.h"]                 = "utility";
+    headers["set.h"]                    = "set";
+    headers["sstream.h"]                = "sstream";
+    headers["sstream.tcc"]              = "sstream";
+    headers["stack.h"]                  = "stack";
+    headers["stdexcept.h"]              = "stdexcept";
+    headers["streambuf.h"]              = "streambuf";
+    headers["streambuf.tcc"]            = "streambuf";
+    headers["string.h"]                 = "string";
+    headers["tempbuf.h"]                = "memory";
+    //headers["threads.h"]                who knows
+    headers["tree.h"]                   = "backward/tree.h";
+    headers["uninitialized.h"]          = "memory";
+    headers["utility.h"]                = "utility";
+    headers["valarray.h"]               = "valarray";
+    headers["valarray_array.h"]         = "valarray";
+    headers["valarray_array.tcc"]       = "valarray";
+    headers["valarray_meta.h"]          = "valarray";
+    headers["vector.h"]                 = "vector";
+
+    // C wrappers -- probably was an easier way to do these, but oh well
+    headers["cassert.h"]                = "cassert";
+    headers["cctype.h"]                 = "cctype";
+    headers["cerrno.h"]                 = "cerrno";
+    headers["cfloat.h"]                 = "cfloat";
+    headers["climits.h"]                = "climits";
+    headers["clocale.h"]                = "clocale";
+    headers["cmath.h"]                  = "cmath";
+    headers["csetjmp.h"]                = "csetjmp";
+    headers["csignal.h"]                = "csignal";
+    headers["cstdarg.h"]                = "cstdarg";
+    headers["cstddef.h"]                = "cstddef";
+    headers["cstdio.h"]                 = "cstdio";
+    headers["cstdlib.h"]                = "cstdlib";
+    headers["cstring.h"]                = "cstring";
+    headers["ctime.h"]                  = "ctime";
+    headers["cwchar.h"]                 = "cwchar";
+    headers["cwctype.h"]                = "cwctype";
+}
+
+
+void do_word (std::string const& longheader)
+{
+    std::string::size_type start = 0;
+
+    if (longheader.substr(start,5) == "bits/")  start += 5;
+    if ((longheader.substr(start,4) == "stl_") ||
+        (longheader.substr(start,4) == "std_"))
+    {
+        start += 4;
+    }
+
+    // come on, gdb, find `p' already...
+    const char* p = longheader.substr(start).c_str();
+    Map::iterator word = headers.find(p);
+    if (word != headers.end())
+        std::cout << word->second << '\n';
+    else std::cout << "MAYBE_AN_ERROR_MESSAGE_HERE\n";
+}
+
+
+int main (int argc, char**)
+{
+    if (argc > 1)
+    {
+        std::cerr << usage;
+        exit(0);
+    }
+
+    init_map();
+
+    std::string w;
+    while (std::cin >> w)
+        do_word (w);
+}
+
+// vim:ts=4:et:
+

libstdc++-v3/docs/doxygen/user.cfg.in

@@ -344,13 +344,14 @@ RECURSIVE              = YES
 # subdirectory from a directory tree whose root is specified with the INPUT tag. 
 
 EXCLUDE                = include/c \
-                         include/c_shadow
+                         include/c_shadow \
+                         docs/doxygen/stdheader.cc
 
 # If the value of the INPUT tag contains directories, you can use the 
 # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude 
 # certain files from those directories. 
 
-EXCLUDE_PATTERNS       = 
+EXCLUDE_PATTERNS       = CVS
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or 
 # directories that contain example code fragments that are included (see 
@@ -477,7 +478,7 @@ TOC_EXPAND             = NO
 # top of each HTML page. The value NO (the default) enables the index and 
 # the value YES disables it. 
 
-DISABLE_INDEX          = NO
+DISABLE_INDEX          = YES
 
 # This tag can be used to set the number of enum values (range [1..20]) 
 # that doxygen will group on one line in the generated HTML documentation. 
@@ -601,7 +602,7 @@ RTF_STYLESHEET_FILE    =
 # If the GENERATE_MAN tag is set to YES (the default) Doxygen will 
 # generate man pages 
 
-GENERATE_MAN           = NO
+GENERATE_MAN           = YES
 
 # The MAN_OUTPUT tag is used to specify where the man pages will be put. 
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be 

libstdc++-v3/include/std/algorithm

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file algorithm
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_ALGORITHM
 #include <bits/std_algorithm.h>
 #endif

libstdc++-v3/include/std/bitset

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file bitset
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_BITSET
 #include <bits/std_bitset.h>
 #endif

libstdc++-v3/include/std/cassert

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cassert
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c assert.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 // This one should not have include guards.
 #include <bits/std_cassert.h>
 

libstdc++-v3/include/std/cctype

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cctype
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c ctype.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CCTYPE
 #include <bits/std_cctype.h>
 #endif

libstdc++-v3/include/std/cerrno

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cerrno
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c errno.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CERRNO
 #include <bits/std_cerrno.h>
 #endif

libstdc++-v3/include/std/cfloat

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cfloat
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c float.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CFLOAT
 #include <bits/std_cfloat.h>
 #endif

libstdc++-v3/include/std/ciso646

@@ -26,3 +26,13 @@
 // the GNU General Public License.  This exception does not however
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
+
+/** @file ciso646
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c iso646.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+

libstdc++-v3/include/std/climits

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file climits
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c limits.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CLIMITS
 #include <bits/std_climits.h>
 #endif

libstdc++-v3/include/std/clocale

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file clocale
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c locale.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CLOCALE
 #include <bits/std_clocale.h>
 #endif

libstdc++-v3/include/std/cmath

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cmath
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c math.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CMATH
 #include <bits/std_cmath.h>
 #endif

libstdc++-v3/include/std/complex

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file complex
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_COMPLEX
 #include <bits/std_complex.h>
 #endif

libstdc++-v3/include/std/csetjmp

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file csetjmp
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c setjmp.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CSETJMP
 #include <bits/std_csetjmp.h>
 #endif

libstdc++-v3/include/std/csignal

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file csignal
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c signal.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CSIGNAL
 #include <bits/std_csignal.h>
 #endif

libstdc++-v3/include/std/cstdarg

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cstdarg
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c stdarg.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CSTDARG
 #include <bits/std_cstdarg.h>
 #endif

libstdc++-v3/include/std/cstddef

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cstddef
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c stddef.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CSTDDEF
 #include <bits/std_cstddef.h>
 #endif

libstdc++-v3/include/std/cstdio

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cstdio
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c stdio.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CSTDIO
 #include <bits/std_cstdio.h>
 #endif

libstdc++-v3/include/std/cstdlib

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cstdlib
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c stdlib.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CSTDLIB
 #include <bits/std_cstdlib.h>
 #endif

libstdc++-v3/include/std/cstring

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cstring
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c string.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CSTRING
 #include <bits/std_cstring.h>
 #endif

libstdc++-v3/include/std/ctime

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file ctime
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c time.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CTIME
 #include <bits/std_ctime.h>
 #endif

libstdc++-v3/include/std/cwchar

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cwchar
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c wchar.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CWCHAR
 #include <bits/std_cwchar.h>
 #endif

libstdc++-v3/include/std/cwctype

@@ -27,6 +27,15 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file cwctype
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ *
+ *  This is the C++ version of the Standard C Library header @c wctype.h,
+ *  and its contents are (mostly) the same as that header, but are all
+ *  contained in the namespace @c std.
+ */
+
 #ifndef _CPP_CWCTYPE
 #include <bits/std_cwctype.h>
 #endif

libstdc++-v3/include/std/deque

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file deque
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_DEQUE
 #include <bits/std_deque.h>
 #endif

libstdc++-v3/include/std/fstream

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file fstream
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_FSTREAM
 #include <bits/std_fstream.h>
 #endif

libstdc++-v3/include/std/functional

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file functional
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_FUNCTIONAL
 #include <bits/std_functional.h>
 #endif

libstdc++-v3/include/std/iomanip

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file iomanip
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_IOMANIP
 #include <bits/std_iomanip.h>
 #endif

libstdc++-v3/include/std/ios

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file ios
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_IOS
 #include <bits/std_ios.h>
 #endif

libstdc++-v3/include/std/iosfwd

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file iosfwd
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_IOSFWD
 #include <bits/std_iosfwd.h>
 #endif

libstdc++-v3/include/std/iostream

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file iostream
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_IOSTREAM
 #include <bits/std_iostream.h>
 #endif

libstdc++-v3/include/std/istream

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file istream
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_ISTREAM
 #include <bits/std_istream.h>
 #endif

libstdc++-v3/include/std/iterator

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file iterator
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_ITERATOR
 #include <bits/std_iterator.h>
 #endif

libstdc++-v3/include/std/limits

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file limits
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_LIMITS
 #include <bits/std_limits.h>
 #endif

libstdc++-v3/include/std/list

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file list
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_LIST
 #include <bits/std_list.h>
 #endif

libstdc++-v3/include/std/locale

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file locale
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_LOCALE
 #include <bits/std_locale.h>
 #endif

libstdc++-v3/include/std/map

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file map
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_MAP
 #include <bits/std_map.h>
 #endif

libstdc++-v3/include/std/memory

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file memory
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_MEMORY
 #include <bits/std_memory.h>
 #endif

libstdc++-v3/include/std/numeric

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file numeric
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_NUMERIC
 #include <bits/std_numeric.h>
 #endif

libstdc++-v3/include/std/ostream

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file ostream
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_OSTREAM
 #include <bits/std_ostream.h>
 #endif

libstdc++-v3/include/std/queue

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file queue
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_QUEUE
 #include <bits/std_queue.h>
 #endif

libstdc++-v3/include/std/set

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file set
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_SET
 #include <bits/std_set.h>
 #endif

libstdc++-v3/include/std/sstream

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file sstream
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_SSTREAM
 #include <bits/std_sstream.h>
 #endif

libstdc++-v3/include/std/stack

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file stack
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_STACK
 #include <bits/std_stack.h>
 #endif

libstdc++-v3/include/std/stdexcept

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file stdexcept
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_STDEXCEPT
 #include <bits/std_stdexcept.h>
 #endif

libstdc++-v3/include/std/streambuf

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file streambuf
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_STREAMBUF
 #include <bits/std_streambuf.h>
 #endif

libstdc++-v3/include/std/string

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file string
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_STRING
 #include <bits/std_string.h>
 #endif

libstdc++-v3/include/std/utility

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file utility
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_UTILITY
 #include <bits/std_utility.h>
 #endif

libstdc++-v3/include/std/valarray

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file valarray
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_VALARRAY
 #include <bits/std_valarray.h>
 #endif

libstdc++-v3/include/std/vector

@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file vector
+ *  This is a Standard C++ Library file.  You should @c #include this file
+ *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
+ */
+
 #ifndef _CPP_VECTOR
 #include <bits/std_vector.h>
 #endif