*: 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

47 files changed, 308 insertions, 0 deletions

diff --git a/libstdc++-v3/include/std/algorithm b/libstdc++-v3/include/std/algorithm
index 06a553f..33ed872 100644
--- a/libstdc++-v3/include/std/algorithm
+++ b/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
diff --git a/libstdc++-v3/include/std/bitset b/libstdc++-v3/include/std/bitset
index 9ce6c79..830ee7c 100644
--- a/libstdc++-v3/include/std/bitset
+++ b/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
diff --git a/libstdc++-v3/include/std/cassert b/libstdc++-v3/include/std/cassert
index fe0b8b5..5cb1e01 100644
--- a/libstdc++-v3/include/std/cassert
+++ b/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>
 
diff --git a/libstdc++-v3/include/std/cctype b/libstdc++-v3/include/std/cctype
index 868e4be..b5bf928 100644
--- a/libstdc++-v3/include/std/cctype
+++ b/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
diff --git a/libstdc++-v3/include/std/cerrno b/libstdc++-v3/include/std/cerrno
index b7bfe3a..0c17749 100644
--- a/libstdc++-v3/include/std/cerrno
+++ b/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
diff --git a/libstdc++-v3/include/std/cfloat b/libstdc++-v3/include/std/cfloat
index d91824d..fa5756d 100644
--- a/libstdc++-v3/include/std/cfloat
+++ b/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
diff --git a/libstdc++-v3/include/std/ciso646 b/libstdc++-v3/include/std/ciso646
index f5dd444..c9f49fb 100644
--- a/libstdc++-v3/include/std/ciso646
+++ b/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.
+ */
+
diff --git a/libstdc++-v3/include/std/climits b/libstdc++-v3/include/std/climits
index afadc64..345ad61 100644
--- a/libstdc++-v3/include/std/climits
+++ b/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
diff --git a/libstdc++-v3/include/std/clocale b/libstdc++-v3/include/std/clocale
index 8a62dfa..3775010 100644
--- a/libstdc++-v3/include/std/clocale
+++ b/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
diff --git a/libstdc++-v3/include/std/cmath b/libstdc++-v3/include/std/cmath
index 95da649..d565307 100644
--- a/libstdc++-v3/include/std/cmath
+++ b/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
diff --git a/libstdc++-v3/include/std/complex b/libstdc++-v3/include/std/complex
index dfc144f..6b7abcf 100644
--- a/libstdc++-v3/include/std/complex
+++ b/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
diff --git a/libstdc++-v3/include/std/csetjmp b/libstdc++-v3/include/std/csetjmp
index ce6fb32..daf11b3 100644
--- a/libstdc++-v3/include/std/csetjmp
+++ b/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
diff --git a/libstdc++-v3/include/std/csignal b/libstdc++-v3/include/std/csignal
index b3da42a..3790ff5 100644
--- a/libstdc++-v3/include/std/csignal
+++ b/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
diff --git a/libstdc++-v3/include/std/cstdarg b/libstdc++-v3/include/std/cstdarg
index 36032b2..8dfe625 100644
--- a/libstdc++-v3/include/std/cstdarg
+++ b/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
diff --git a/libstdc++-v3/include/std/cstddef b/libstdc++-v3/include/std/cstddef
index 086bb72..4b3d1f5 100644
--- a/libstdc++-v3/include/std/cstddef
+++ b/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
diff --git a/libstdc++-v3/include/std/cstdio b/libstdc++-v3/include/std/cstdio
index 4d8aced..b546585 100644
--- a/libstdc++-v3/include/std/cstdio
+++ b/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
diff --git a/libstdc++-v3/include/std/cstdlib b/libstdc++-v3/include/std/cstdlib
index 7796c6b..2feeb53 100644
--- a/libstdc++-v3/include/std/cstdlib
+++ b/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
diff --git a/libstdc++-v3/include/std/cstring b/libstdc++-v3/include/std/cstring
index 8d30ba8..5652803 100644
--- a/libstdc++-v3/include/std/cstring
+++ b/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
diff --git a/libstdc++-v3/include/std/ctime b/libstdc++-v3/include/std/ctime
index b19136e..e1d6bc9 100644
--- a/libstdc++-v3/include/std/ctime
+++ b/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
diff --git a/libstdc++-v3/include/std/cwchar b/libstdc++-v3/include/std/cwchar
index 311b2e9..aa928d7 100644
--- a/libstdc++-v3/include/std/cwchar
+++ b/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
diff --git a/libstdc++-v3/include/std/cwctype b/libstdc++-v3/include/std/cwctype
index 4cf2e7d..b0de79e 100644
--- a/libstdc++-v3/include/std/cwctype
+++ b/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
diff --git a/libstdc++-v3/include/std/deque b/libstdc++-v3/include/std/deque
index c8ee81e..222d7ca 100644
--- a/libstdc++-v3/include/std/deque
+++ b/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
diff --git a/libstdc++-v3/include/std/fstream b/libstdc++-v3/include/std/fstream
index 1a68f5a..9d6fcfc 100644
--- a/libstdc++-v3/include/std/fstream
+++ b/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
diff --git a/libstdc++-v3/include/std/functional b/libstdc++-v3/include/std/functional
index ea48352..10c5525 100644
--- a/libstdc++-v3/include/std/functional
+++ b/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
diff --git a/libstdc++-v3/include/std/iomanip b/libstdc++-v3/include/std/iomanip
index 2aa00fa..5659918 100644
--- a/libstdc++-v3/include/std/iomanip
+++ b/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
diff --git a/libstdc++-v3/include/std/ios b/libstdc++-v3/include/std/ios
index ff398de..a017dd8 100644
--- a/libstdc++-v3/include/std/ios
+++ b/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
diff --git a/libstdc++-v3/include/std/iosfwd b/libstdc++-v3/include/std/iosfwd
index 3756982..e48516a 100644
--- a/libstdc++-v3/include/std/iosfwd
+++ b/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
diff --git a/libstdc++-v3/include/std/iostream b/libstdc++-v3/include/std/iostream
index a85fd08..a8098c6 100644
--- a/libstdc++-v3/include/std/iostream
+++ b/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
diff --git a/libstdc++-v3/include/std/istream b/libstdc++-v3/include/std/istream
index 9c6bc55..c383506 100644
--- a/libstdc++-v3/include/std/istream
+++ b/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
diff --git a/libstdc++-v3/include/std/iterator b/libstdc++-v3/include/std/iterator
index 2560439..6e42f56 100644
--- a/libstdc++-v3/include/std/iterator
+++ b/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
diff --git a/libstdc++-v3/include/std/limits b/libstdc++-v3/include/std/limits
index 8a52c9c..ea55c7f 100644
--- a/libstdc++-v3/include/std/limits
+++ b/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
diff --git a/libstdc++-v3/include/std/list b/libstdc++-v3/include/std/list
index a32e18d..51490ee 100644
--- a/libstdc++-v3/include/std/list
+++ b/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
diff --git a/libstdc++-v3/include/std/locale b/libstdc++-v3/include/std/locale
index 56c416d..5a1d622 100644
--- a/libstdc++-v3/include/std/locale
+++ b/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
diff --git a/libstdc++-v3/include/std/map b/libstdc++-v3/include/std/map
index 06c638d..3d10673 100644
--- a/libstdc++-v3/include/std/map
+++ b/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
diff --git a/libstdc++-v3/include/std/memory b/libstdc++-v3/include/std/memory
index ca98df6..a52f492 100644
--- a/libstdc++-v3/include/std/memory
+++ b/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
diff --git a/libstdc++-v3/include/std/numeric b/libstdc++-v3/include/std/numeric
index 32ba67d..0d2aea0 100644
--- a/libstdc++-v3/include/std/numeric
+++ b/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
diff --git a/libstdc++-v3/include/std/ostream b/libstdc++-v3/include/std/ostream
index 4564be7..eb4fd68 100644
--- a/libstdc++-v3/include/std/ostream
+++ b/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
diff --git a/libstdc++-v3/include/std/queue b/libstdc++-v3/include/std/queue
index c4464bf..b3d9cdb 100644
--- a/libstdc++-v3/include/std/queue
+++ b/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
diff --git a/libstdc++-v3/include/std/set b/libstdc++-v3/include/std/set
index 62d6718..414b04c 100644
--- a/libstdc++-v3/include/std/set
+++ b/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
diff --git a/libstdc++-v3/include/std/sstream b/libstdc++-v3/include/std/sstream
index 1a393ed..2a53e36 100644
--- a/libstdc++-v3/include/std/sstream
+++ b/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
diff --git a/libstdc++-v3/include/std/stack b/libstdc++-v3/include/std/stack
index 793a003..e901f84 100644
--- a/libstdc++-v3/include/std/stack
+++ b/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
diff --git a/libstdc++-v3/include/std/stdexcept b/libstdc++-v3/include/std/stdexcept
index d9e93f2..03e89e8 100644
--- a/libstdc++-v3/include/std/stdexcept
+++ b/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
diff --git a/libstdc++-v3/include/std/streambuf b/libstdc++-v3/include/std/streambuf
index ec6c7b5..c0f4dd7 100644
--- a/libstdc++-v3/include/std/streambuf
+++ b/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
diff --git a/libstdc++-v3/include/std/string b/libstdc++-v3/include/std/string
index a766cdd..0229afd 100644
--- a/libstdc++-v3/include/std/string
+++ b/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
diff --git a/libstdc++-v3/include/std/utility b/libstdc++-v3/include/std/utility
index 787e799..28822fa 100644
--- a/libstdc++-v3/include/std/utility
+++ b/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
diff --git a/libstdc++-v3/include/std/valarray b/libstdc++-v3/include/std/valarray
index cb13d82..e20b7b8 100644
--- a/libstdc++-v3/include/std/valarray
+++ b/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
diff --git a/libstdc++-v3/include/std/vector b/libstdc++-v3/include/std/vector
index ce2f51e..8fa361d 100644
--- a/libstdc++-v3/include/std/vector
+++ b/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