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.


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

81 files changed, 434 insertions, 113 deletions

diff --git a/libstdc++-v3/include/bits/basic_file.h b/libstdc++-v3/include/bits/basic_file.h
index 65081a0af10..e7c220a3801 100644
--- a/libstdc++-v3/include/bits/basic_file.h
+++ b/libstdc++-v3/include/bits/basic_file.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.8  File-based streams
 //
 
+/** @file basic_file.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BASIC_FILE
 #define _CPP_BASIC_FILE		1
 
@@ -121,7 +126,9 @@ namespace std
 #endif
     {
 #if _GLIBCPP_BASIC_FILE_ENCAPSULATION
+      // underlying data source/sink
       __c_file_type* 	_M_cfile;
+      // true iff we opened _M_cfile, and thus must close it ourselves
       bool 		_M_cfile_created;
 #else
 # ifdef _GLIBCPP_USE_WCHAR_T
@@ -142,8 +149,10 @@ namespace std
 
       // Used for opening the standard streams, cin, cout, cerr, clog,
       // and their wide-stream equivalents. Instead of calling open, it
-      // just sets __c_file_type->_fileno and the respective _flags bits, and
-      // returns.
+      // just sets
+      //  - for libio:  __c_file_type->_fileno and the respective _flags bits
+      //  - for stdio:  _M_cfile = __file and some internal flags
+      // and returns.
       __basic_file*
       sys_open(__c_file_type* __file, ios_base::openmode __mode);
 
diff --git a/libstdc++-v3/include/bits/basic_ios.h b/libstdc++-v3/include/bits/basic_ios.h
index 883a4cace50..cc393aaf311 100644
--- a/libstdc++-v3/include/bits/basic_ios.h
+++ b/libstdc++-v3/include/bits/basic_ios.h
@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file basic_ios.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_BASICIOS_H
 #define _CPP_BITS_BASICIOS_H 1
 
diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h
index a2fb1e0932d..37a30af7ca4 100644
--- a/libstdc++-v3/include/bits/basic_string.h
+++ b/libstdc++-v3/include/bits/basic_string.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 21 Strings library
 //
 
+/** @file basic_string.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_STRING_H
 #define _CPP_BITS_STRING_H	1
 
diff --git a/libstdc++-v3/include/bits/boost_concept_check.h b/libstdc++-v3/include/bits/boost_concept_check.h
index 91d7019155e..b4f0d06f12e 100644
--- a/libstdc++-v3/include/bits/boost_concept_check.h
+++ b/libstdc++-v3/include/bits/boost_concept_check.h
@@ -7,6 +7,12 @@
 //
 
 // GCC Note:  based on version 1.12.0 of the Boost library.
+
+/** @file boost_concept_check.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _GLIBCPP_BOOST_CONCEPT_CHECK
 #define _GLIBCPP_BOOST_CONCEPT_CHECK 1
 
diff --git a/libstdc++-v3/include/bits/char_traits.h b/libstdc++-v3/include/bits/char_traits.h
index a468bed90af..710e0eb6a53 100644
--- a/libstdc++-v3/include/bits/char_traits.h
+++ b/libstdc++-v3/include/bits/char_traits.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 21  Strings library
 //
 
+/** @file char_traits.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_CHAR_TRAITS_H
 #define _CPP_BITS_CHAR_TRAITS_H 1
 
diff --git a/libstdc++-v3/include/bits/codecvt.h b/libstdc++-v3/include/bits/codecvt.h
index 441f40c9fe3..506752f3432 100644
--- a/libstdc++-v3/include/bits/codecvt.h
+++ b/libstdc++-v3/include/bits/codecvt.h
@@ -31,10 +31,13 @@
 // ISO C++ 14882: 22.2.1.5 Template class codecvt
 //
 
-// Warning: this file is not meant for user inclusion.  Use <locale>.
-
 // Written by Benjamin Kosnik <bkoz@cygnus.com>
 
+/** @file codecvt.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_CODECVT_H
 #define _CPP_BITS_CODECVT_H	1
 
diff --git a/libstdc++-v3/include/bits/concept_check.h b/libstdc++-v3/include/bits/concept_check.h
index 4ee8d9b6cc8..92ceefbd685 100644
--- a/libstdc++-v3/include/bits/concept_check.h
+++ b/libstdc++-v3/include/bits/concept_check.h
@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file concept_check.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _GLIBCPP_CONCEPT_CHECK
 #define _GLIBCPP_CONCEPT_CHECK 1
 
diff --git a/libstdc++-v3/include/bits/cpp_type_traits.h b/libstdc++-v3/include/bits/cpp_type_traits.h
index 61cc45d47fa..693fc91a627 100644
--- a/libstdc++-v3/include/bits/cpp_type_traits.h
+++ b/libstdc++-v3/include/bits/cpp_type_traits.h
@@ -29,6 +29,11 @@
 
 // Written by Gabriel Dos Reis <dosreis@cmla.ens-cachan.fr>
 
+/** @file cpp_type_traits.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_CPP_TYPE_TRAITS_H
 #define _CPP_BITS_CPP_TYPE_TRAITS_H 1
 
diff --git a/libstdc++-v3/include/bits/fpos.h b/libstdc++-v3/include/bits/fpos.h
index 86eb5c38e49..119fbe7f528 100644
--- a/libstdc++-v3/include/bits/fpos.h
+++ b/libstdc++-v3/include/bits/fpos.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27 Input/output library
 //
 
+/** @file fpos.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_FPOS_H
 #define _CPP_BITS_FPOS_H 1
 
diff --git a/libstdc++-v3/include/bits/gslice.h b/libstdc++-v3/include/bits/gslice.h
index df8ecbe8be9..58a36fb174d 100644
--- a/libstdc++-v3/include/bits/gslice.h
+++ b/libstdc++-v3/include/bits/gslice.h
@@ -29,6 +29,11 @@
 
 // Written by Gabriel Dos Reis <Gabriel.Dos-Reis@DPTMaths.ENS-Cachan.Fr>
 
+/** @file gslice.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_GSLICE_H
 #define _CPP_BITS_GSLICE_H 1
 
diff --git a/libstdc++-v3/include/bits/gslice_array.h b/libstdc++-v3/include/bits/gslice_array.h
index 3e2d12fd04d..eca541e636e 100644
--- a/libstdc++-v3/include/bits/gslice_array.h
+++ b/libstdc++-v3/include/bits/gslice_array.h
@@ -29,6 +29,11 @@
 
 // Written by Gabriel Dos Reis <Gabriel.Dos-Reis@DPTMaths.ENS-Cachan.Fr>
 
+/** @file gslice_array.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_GSLICE_ARRAY
 #define _CPP_BITS_GSLICE_ARRAY 1
 
diff --git a/libstdc++-v3/include/bits/indirect_array.h b/libstdc++-v3/include/bits/indirect_array.h
index 5eb3fb04edd..d928258cd15 100644
--- a/libstdc++-v3/include/bits/indirect_array.h
+++ b/libstdc++-v3/include/bits/indirect_array.h
@@ -29,6 +29,11 @@
 
 // Written by Gabriel Dos Reis <Gabriel.Dos-Reis@DPTMaths.ENS-Cachan.Fr>
 
+/** @file indirect_array.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_INDIRECT_ARRAY_H
 #define _CPP_BITS_INDIRECT_ARRAY_H 1
 
diff --git a/libstdc++-v3/include/bits/ios_base.h b/libstdc++-v3/include/bits/ios_base.h
index b2b8da060e5..bf9fe693199 100644
--- a/libstdc++-v3/include/bits/ios_base.h
+++ b/libstdc++-v3/include/bits/ios_base.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.8  File-based streams
 //
 
+/** @file ios_base.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_IOSBASE_H
 #define _CPP_BITS_IOSBASE_H 1
 
diff --git a/libstdc++-v3/include/bits/locale_facets.h b/libstdc++-v3/include/bits/locale_facets.h
index 2c6419b0459..94f607ac9c0 100644
--- a/libstdc++-v3/include/bits/locale_facets.h
+++ b/libstdc++-v3/include/bits/locale_facets.h
@@ -31,7 +31,10 @@
 // ISO C++ 14882: 22.1  Locales
 //
 
-// Warning: this file is not meant for user inclusion.  Use <locale>.
+/** @file locale_facets.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
 
 #ifndef _CPP_BITS_LOCFACETS_H
 #define _CPP_BITS_LOCFACETS_H	1
diff --git a/libstdc++-v3/include/bits/localefwd.h b/libstdc++-v3/include/bits/localefwd.h
index e6bd6cc25af..af48b600c0f 100644
--- a/libstdc++-v3/include/bits/localefwd.h
+++ b/libstdc++-v3/include/bits/localefwd.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 22.1  Locales
 //
 
+/** @file localefwd.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_LOCCORE_H
 #define _CPP_BITS_LOCCORE_H	1
 
diff --git a/libstdc++-v3/include/bits/mask_array.h b/libstdc++-v3/include/bits/mask_array.h
index b2399ba1fa7..13c01d3cc22 100644
--- a/libstdc++-v3/include/bits/mask_array.h
+++ b/libstdc++-v3/include/bits/mask_array.h
@@ -29,6 +29,11 @@
 
 // Written by Gabriel Dos Reis <Gabriel.Dos-Reis@DPTMaths.ENS-Cachan.Fr>
 
+/** @file mask_array.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_MASK_ARRAY_H
 #define _CPP_BITS_MASK_ARRAY_H 1
 
diff --git a/libstdc++-v3/include/bits/pthread_allocimpl.h b/libstdc++-v3/include/bits/pthread_allocimpl.h
index 1c52127f192..ca0f980fbf4 100644
--- a/libstdc++-v3/include/bits/pthread_allocimpl.h
+++ b/libstdc++-v3/include/bits/pthread_allocimpl.h
@@ -40,6 +40,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file pthread_allocimpl.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_PTHREAD_ALLOCIMPL_H
 #define _CPP_BITS_PTHREAD_ALLOCIMPL_H 1
 
diff --git a/libstdc++-v3/include/bits/slice.h b/libstdc++-v3/include/bits/slice.h
index 5efb6e8cf4c..d3da664f8d1 100644
--- a/libstdc++-v3/include/bits/slice.h
+++ b/libstdc++-v3/include/bits/slice.h
@@ -29,6 +29,11 @@
 
 // Written by Gabriel Dos Reis <Gabriel.Dos-Reis@DPTMaths.ENS-Cachan.Fr>
 
+/** @file slice.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_SLICE_H
 #define _CPP_BITS_SLICE_H 1
 
diff --git a/libstdc++-v3/include/bits/slice_array.h b/libstdc++-v3/include/bits/slice_array.h
index b2b118987fd..4e82cebf82d 100644
--- a/libstdc++-v3/include/bits/slice_array.h
+++ b/libstdc++-v3/include/bits/slice_array.h
@@ -29,6 +29,11 @@
 
 // Written by Gabriel Dos Reis <Gabriel.Dos-Reis@DPTMaths.ENS-Cachan.Fr>
 
+/** @file slice_array.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_SLICE_ARRAY_H
 #define _CPP_BITS_SLICE_ARRAY_H 1
 
diff --git a/libstdc++-v3/include/bits/std_algorithm.h b/libstdc++-v3/include/bits/std_algorithm.h
index 4914e1da75f..746eb47541b 100644
--- a/libstdc++-v3/include/bits/std_algorithm.h
+++ b/libstdc++-v3/include/bits/std_algorithm.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_algorithm.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_ALGORITHM
 #define _CPP_ALGORITHM 1
 
diff --git a/libstdc++-v3/include/bits/std_bitset.h b/libstdc++-v3/include/bits/std_bitset.h
index d8524cac390..14b5051e456 100644
--- a/libstdc++-v3/include/bits/std_bitset.h
+++ b/libstdc++-v3/include/bits/std_bitset.h
@@ -40,6 +40,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */ 
 
+/** @file std_bitset.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef __SGI_STL_BITSET
 #define __SGI_STL_BITSET
 
diff --git a/libstdc++-v3/include/bits/std_complex.h b/libstdc++-v3/include/bits/std_complex.h
index 85b8d295830..d07a6b791df 100644
--- a/libstdc++-v3/include/bits/std_complex.h
+++ b/libstdc++-v3/include/bits/std_complex.h
@@ -34,6 +34,11 @@
 // Improved by Gabriel Dos Reis <dosreis@cmla.ens-cachan.fr>
 //
 
+/** @file std_complex.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_COMPLEX
 #define _CPP_COMPLEX	1
 
diff --git a/libstdc++-v3/include/bits/std_deque.h b/libstdc++-v3/include/bits/std_deque.h
index 2ac8f88353a..394eef3b845 100644
--- a/libstdc++-v3/include/bits/std_deque.h
+++ b/libstdc++-v3/include/bits/std_deque.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_deque.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_DEQUE
 #define _CPP_DEQUE 1
 
diff --git a/libstdc++-v3/include/bits/std_fstream.h b/libstdc++-v3/include/bits/std_fstream.h
index a0604abbe0d..52c62d4b198 100644
--- a/libstdc++-v3/include/bits/std_fstream.h
+++ b/libstdc++-v3/include/bits/std_fstream.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.8  File-based streams
 //
 
+/** @file std_fstream.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_FSTREAM
 #define _CPP_FSTREAM	1
 
diff --git a/libstdc++-v3/include/bits/std_functional.h b/libstdc++-v3/include/bits/std_functional.h
index bf67c3a0c18..82863cc3e3c 100644
--- a/libstdc++-v3/include/bits/std_functional.h
+++ b/libstdc++-v3/include/bits/std_functional.h
@@ -41,6 +41,11 @@
  *
  */
 
+/** @file std_functional.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_FUNCTIONAL
 #define _CPP_FUNCTIONAL 1
 
diff --git a/libstdc++-v3/include/bits/std_iomanip.h b/libstdc++-v3/include/bits/std_iomanip.h
index 5e0cb91bdc1..3d296b56ba2 100644
--- a/libstdc++-v3/include/bits/std_iomanip.h
+++ b/libstdc++-v3/include/bits/std_iomanip.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.6.3  Standard manipulators
 //
 
+/** @file std_iomanip.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_IOMANIP
 #define _CPP_IOMANIP 1
 
diff --git a/libstdc++-v3/include/bits/std_ios.h b/libstdc++-v3/include/bits/std_ios.h
index abedfe6abc4..dfd041f811f 100644
--- a/libstdc++-v3/include/bits/std_ios.h
+++ b/libstdc++-v3/include/bits/std_ios.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.4  Iostreams base classes
 //
 
+/** @file std_ios.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_IOS
 #define _CPP_IOS	1
 
diff --git a/libstdc++-v3/include/bits/std_iosfwd.h b/libstdc++-v3/include/bits/std_iosfwd.h
index 03ce3d58839..93c30b3fbf4 100644
--- a/libstdc++-v3/include/bits/std_iosfwd.h
+++ b/libstdc++-v3/include/bits/std_iosfwd.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.2  Forward declarations
 //
 
+/** @file std_iosfwd.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_IOSFWD
 #define _CPP_IOSFWD 1
 
diff --git a/libstdc++-v3/include/bits/std_iostream.h b/libstdc++-v3/include/bits/std_iostream.h
index 45d7a44990b..32893fa55cc 100644
--- a/libstdc++-v3/include/bits/std_iostream.h
+++ b/libstdc++-v3/include/bits/std_iostream.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.3  Standard iostream objects
 //
 
+/** @file std_iostream.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_IOSTREAM
 #define _CPP_IOSTREAM	1
 
diff --git a/libstdc++-v3/include/bits/std_istream.h b/libstdc++-v3/include/bits/std_istream.h
index 66dabde3a8f..3f690d7870e 100644
--- a/libstdc++-v3/include/bits/std_istream.h
+++ b/libstdc++-v3/include/bits/std_istream.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.6.1  Input streams
 //
 
+/** @file std_istream.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_ISTREAM
 #define _CPP_ISTREAM	1
 
diff --git a/libstdc++-v3/include/bits/std_iterator.h b/libstdc++-v3/include/bits/std_iterator.h
index ec670755a93..3e3541c6089 100644
--- a/libstdc++-v3/include/bits/std_iterator.h
+++ b/libstdc++-v3/include/bits/std_iterator.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_iterator.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_ITERATOR
 #define _CPP_ITERATOR 1
 
diff --git a/libstdc++-v3/include/bits/std_limits.h b/libstdc++-v3/include/bits/std_limits.h
index 10a5a38d213..74184e3b934 100644
--- a/libstdc++-v3/include/bits/std_limits.h
+++ b/libstdc++-v3/include/bits/std_limits.h
@@ -35,6 +35,11 @@
 // 18.2.1
 //
 
+/** @file std_limits.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_NUMERIC_LIMITS
 #define _CPP_NUMERIC_LIMITS 1
 
diff --git a/libstdc++-v3/include/bits/std_list.h b/libstdc++-v3/include/bits/std_list.h
index e34734d1d44..683e0a7e66d 100644
--- a/libstdc++-v3/include/bits/std_list.h
+++ b/libstdc++-v3/include/bits/std_list.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_list.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_LIST
 #define _CPP_LIST 1
 
diff --git a/libstdc++-v3/include/bits/std_locale.h b/libstdc++-v3/include/bits/std_locale.h
index 1b3b58f22d9..82089d01539 100644
--- a/libstdc++-v3/include/bits/std_locale.h
+++ b/libstdc++-v3/include/bits/std_locale.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 22.1  Locales
 //
 
+/** @file std_locale.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_LOCALE
 #define _CPP_LOCALE	1
 
diff --git a/libstdc++-v3/include/bits/std_map.h b/libstdc++-v3/include/bits/std_map.h
index 5239bd078f5..0dd38bfafd3 100644
--- a/libstdc++-v3/include/bits/std_map.h
+++ b/libstdc++-v3/include/bits/std_map.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_map.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_MAP
 #define _CPP_MAP 1
 
diff --git a/libstdc++-v3/include/bits/std_memory.h b/libstdc++-v3/include/bits/std_memory.h
index 1aab9ffe13f..d0b36965384 100644
--- a/libstdc++-v3/include/bits/std_memory.h
+++ b/libstdc++-v3/include/bits/std_memory.h
@@ -41,6 +41,11 @@
  *
  */
 
+/** @file std_memory.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_MEMORY
 #define _CPP_MEMORY 1
 
diff --git a/libstdc++-v3/include/bits/std_numeric.h b/libstdc++-v3/include/bits/std_numeric.h
index 88304156cee..097c9c35b4b 100644
--- a/libstdc++-v3/include/bits/std_numeric.h
+++ b/libstdc++-v3/include/bits/std_numeric.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_numeric.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_NUMERIC
 #define _CPP_NUMERIC 1
 
diff --git a/libstdc++-v3/include/bits/std_ostream.h b/libstdc++-v3/include/bits/std_ostream.h
index 0d00e557d70..c1c79db7fb0 100644
--- a/libstdc++-v3/include/bits/std_ostream.h
+++ b/libstdc++-v3/include/bits/std_ostream.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.6.2  Output streams
 //
 
+/** @file std_ostream.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_OSTREAM
 #define _CPP_OSTREAM	1
 
diff --git a/libstdc++-v3/include/bits/std_queue.h b/libstdc++-v3/include/bits/std_queue.h
index 87dc80a98c0..ecf7f4c135d 100644
--- a/libstdc++-v3/include/bits/std_queue.h
+++ b/libstdc++-v3/include/bits/std_queue.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_queue.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_QUEUE
 #define _CPP_QUEUE 1
 
diff --git a/libstdc++-v3/include/bits/std_set.h b/libstdc++-v3/include/bits/std_set.h
index 9f3f006f65f..dab8e71af5b 100644
--- a/libstdc++-v3/include/bits/std_set.h
+++ b/libstdc++-v3/include/bits/std_set.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_set.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_SET
 #define _CPP_SET 1
 
diff --git a/libstdc++-v3/include/bits/std_sstream.h b/libstdc++-v3/include/bits/std_sstream.h
index 0dcd7b96c70..1b8d5eff947 100644
--- a/libstdc++-v3/include/bits/std_sstream.h
+++ b/libstdc++-v3/include/bits/std_sstream.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.7  String-based streams
 //
 
+/** @file std_sstream.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_SSTREAM
 #define _CPP_SSTREAM	1
 
diff --git a/libstdc++-v3/include/bits/std_stack.h b/libstdc++-v3/include/bits/std_stack.h
index 32b1971e5fa..166f428bf85 100644
--- a/libstdc++-v3/include/bits/std_stack.h
+++ b/libstdc++-v3/include/bits/std_stack.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_stack.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_STACK
 #define _CPP_STACK 1
 
diff --git a/libstdc++-v3/include/bits/std_streambuf.h b/libstdc++-v3/include/bits/std_streambuf.h
index 8975f174849..8ef20ff4cfb 100644
--- a/libstdc++-v3/include/bits/std_streambuf.h
+++ b/libstdc++-v3/include/bits/std_streambuf.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 27.5  Stream buffers
 //
 
+/** @file std_streambuf.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_STREAMBUF
 #define _CPP_STREAMBUF	1
 
@@ -95,7 +100,7 @@ namespace std
       // the same place.  True for fstreams, false for sstreams.
       bool 			_M_buf_unified;	
 
-       // This is based on _IO_FILE, just reordered to be more
+      // This is based on _IO_FILE, just reordered to be more
       // consistent, and is intended to be the most minimal abstraction
       // for an internal buffer.
       // get == input == read
diff --git a/libstdc++-v3/include/bits/std_string.h b/libstdc++-v3/include/bits/std_string.h
index 7dd0013c4ed..09347a9b26d 100644
--- a/libstdc++-v3/include/bits/std_string.h
+++ b/libstdc++-v3/include/bits/std_string.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 21  Strings library
 //
 
+/** @file std_string.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_STRING
 #define _CPP_STRING	1
 
diff --git a/libstdc++-v3/include/bits/std_utility.h b/libstdc++-v3/include/bits/std_utility.h
index 505f5266af3..5917c833818 100644
--- a/libstdc++-v3/include/bits/std_utility.h
+++ b/libstdc++-v3/include/bits/std_utility.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_utility.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_UTILITY
 #define _CPP_UTILITY 1
 
diff --git a/libstdc++-v3/include/bits/std_valarray.h b/libstdc++-v3/include/bits/std_valarray.h
index a250dfd122e..5f4c112f8e9 100644
--- a/libstdc++-v3/include/bits/std_valarray.h
+++ b/libstdc++-v3/include/bits/std_valarray.h
@@ -29,6 +29,11 @@
 
 // Written by Gabriel Dos Reis <Gabriel.Dos-Reis@DPTMaths.ENS-Cachan.Fr>
 
+/** @file std_valarray.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_VALARRAY
 #define _CPP_VALARRAY 1
 
diff --git a/libstdc++-v3/include/bits/std_vector.h b/libstdc++-v3/include/bits/std_vector.h
index 6177b740ae3..995daec7249 100644
--- a/libstdc++-v3/include/bits/std_vector.h
+++ b/libstdc++-v3/include/bits/std_vector.h
@@ -53,6 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file std_vector.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_VECTOR
 #define _CPP_VECTOR 1
 
diff --git a/libstdc++-v3/include/bits/stl_algo.h b/libstdc++-v3/include/bits/stl_algo.h
index 3053515c52f..c909f11a890 100644
--- a/libstdc++-v3/include/bits/stl_algo.h
+++ b/libstdc++-v3/include/bits/stl_algo.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_algo.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_ALGO_H
diff --git a/libstdc++-v3/include/bits/stl_algobase.h b/libstdc++-v3/include/bits/stl_algobase.h
index 7c5c6a02863..a26a8b59de5 100644
--- a/libstdc++-v3/include/bits/stl_algobase.h
+++ b/libstdc++-v3/include/bits/stl_algobase.h
@@ -53,11 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_algobase.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
-
 #ifndef __SGI_STL_INTERNAL_ALGOBASE_H
 #define __SGI_STL_INTERNAL_ALGOBASE_H
 
@@ -81,6 +81,15 @@ namespace std
 
   // swap and iter_swap
 
+  /**
+   *  @brief Swaps the contents of two iterators.
+   *  @param  a  An iterator.
+   *  @param  b  Another iterator.
+   *  @return   Nothing.
+   *
+   *  This function swaps the values pointed to by two iterators, not the
+   *  iterators themselves.
+  */
   template<typename _ForwardIter1, typename _ForwardIter2>
     inline void
     iter_swap(_ForwardIter1 __a, _ForwardIter2 __b)
@@ -99,6 +108,15 @@ namespace std
       *__b = __tmp;
     }
 
+  /**
+   *  @brief Swaps two values.
+   *  @param  a  A thing of arbitrary type.
+   *  @param  b  Another thing of arbitrary type.
+   *  @return   Nothing.
+   *
+   *  This is the simple classic generic implementation.  It will work on
+   *  any type which has a copy constructor and an assignment operator.
+  */
   template<typename _Tp>
     inline void
     swap(_Tp& __a, _Tp& __b)
@@ -117,6 +135,16 @@ namespace std
   #undef min
   #undef max
 
+  /**
+   *  @brief This does what you think it does.
+   *  @param  a  A thing of arbitrary type.
+   *  @param  b  Another thing of arbitrary type.
+   *  @return   The lesser of the parameters.
+   *
+   *  This is the simple classic generic implementation.  It will work on
+   *  temporary expressions, since they are only evaluated once, unlike a
+   *  preprocessor macro.
+  */
   template<typename _Tp>
     inline const _Tp&
     min(const _Tp& __a, const _Tp& __b)
diff --git a/libstdc++-v3/include/bits/stl_alloc.h b/libstdc++-v3/include/bits/stl_alloc.h
index c0a9a46197b..4279ba0321a 100644
--- a/libstdc++-v3/include/bits/stl_alloc.h
+++ b/libstdc++-v3/include/bits/stl_alloc.h
@@ -40,8 +40,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_alloc.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_ALLOC_H
diff --git a/libstdc++-v3/include/bits/stl_bvector.h b/libstdc++-v3/include/bits/stl_bvector.h
index 9a51f5e8996..fddf02ad8e7 100644
--- a/libstdc++-v3/include/bits/stl_bvector.h
+++ b/libstdc++-v3/include/bits/stl_bvector.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_bvector.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_BVECTOR_H
diff --git a/libstdc++-v3/include/bits/stl_construct.h b/libstdc++-v3/include/bits/stl_construct.h
index 385317d51fa..73753b64a14 100644
--- a/libstdc++-v3/include/bits/stl_construct.h
+++ b/libstdc++-v3/include/bits/stl_construct.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_construct.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef _CPP_BITS_STL_CONSTRUCT_H
diff --git a/libstdc++-v3/include/bits/stl_deque.h b/libstdc++-v3/include/bits/stl_deque.h
index 34eafc23934..a1dda2f8b9e 100644
--- a/libstdc++-v3/include/bits/stl_deque.h
+++ b/libstdc++-v3/include/bits/stl_deque.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_deque.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #include <bits/concept_check.h>
diff --git a/libstdc++-v3/include/bits/stl_function.h b/libstdc++-v3/include/bits/stl_function.h
index 51a939a3dcb..9fbead498db 100644
--- a/libstdc++-v3/include/bits/stl_function.h
+++ b/libstdc++-v3/include/bits/stl_function.h
@@ -54,8 +54,8 @@
  */
 
 /** @file stl_function.h
- *  This is an internal header file, included by other STL headers.  You
- *  should not attempt to use it directly.
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_FUNCTION_H
@@ -96,7 +96,7 @@ namespace std
  *  @{
 */
 /**
- *  This is one of the @link s20_3_1_base functor base classes @endlink.
+ *  This is one of the @link s20_3_1_base functor base classes@endlink.
 */
 template <class _Arg, class _Result>
 struct unary_function {
@@ -105,7 +105,7 @@ struct unary_function {
 };
 
 /**
- *  This is one of the @link s20_3_1_base functor base classes @endlink.
+ *  This is one of the @link s20_3_1_base functor base classes@endlink.
 */
 template <class _Arg1, class _Arg2, class _Result>
 struct binary_function {
@@ -119,42 +119,42 @@ struct binary_function {
 /** @defgroup s20_3_2_arithmetic Arithmetic Classes
  *  Because basic math often needs to be done during an algorithm, the library
  *  provides functors for those operations.  See the documentation for
- *  @link s20_3_1_base the base classes @endlink for examples of their use.
+ *  @link s20_3_1_base the base classes@endlink for examples of their use.
  *
  *  @{
 */
-/// One of the @link s20_3_2_arithmetic math functors @endlink.
+/// One of the @link s20_3_2_arithmetic math functors@endlink.
 template <class _Tp>
 struct plus : public binary_function<_Tp,_Tp,_Tp> {
   _Tp operator()(const _Tp& __x, const _Tp& __y) const { return __x + __y; }
 };
 
-/// One of the @link s20_3_2_arithmetic math functors @endlink.
+/// One of the @link s20_3_2_arithmetic math functors@endlink.
 template <class _Tp>
 struct minus : public binary_function<_Tp,_Tp,_Tp> {
   _Tp operator()(const _Tp& __x, const _Tp& __y) const { return __x - __y; }
 };
 
-/// One of the @link s20_3_2_arithmetic math functors @endlink.
+/// One of the @link s20_3_2_arithmetic math functors@endlink.
 template <class _Tp>
 struct multiplies : public binary_function<_Tp,_Tp,_Tp> {
   _Tp operator()(const _Tp& __x, const _Tp& __y) const { return __x * __y; }
 };
 
-/// One of the @link s20_3_2_arithmetic math functors @endlink.
+/// One of the @link s20_3_2_arithmetic math functors@endlink.
 template <class _Tp>
 struct divides : public binary_function<_Tp,_Tp,_Tp> {
   _Tp operator()(const _Tp& __x, const _Tp& __y) const { return __x / __y; }
 };
 
-/// One of the @link s20_3_2_arithmetic math functors @endlink.
+/// One of the @link s20_3_2_arithmetic math functors@endlink.
 template <class _Tp>
 struct modulus : public binary_function<_Tp,_Tp,_Tp> 
 {
   _Tp operator()(const _Tp& __x, const _Tp& __y) const { return __x % __y; }
 };
 
-/// One of the @link s20_3_2_arithmetic math functors @endlink.
+/// One of the @link s20_3_2_arithmetic math functors@endlink.
 template <class _Tp>
 struct negate : public unary_function<_Tp,_Tp> 
 {
@@ -188,42 +188,42 @@ template <class _Tp> inline _Tp identity_element(multiplies<_Tp>) {
  *
  *  @{
 */
-/// One of the @link s20_3_3_comparisons comparison functors @endlink.
+/// One of the @link s20_3_3_comparisons comparison functors@endlink.
 template <class _Tp>
 struct equal_to : public binary_function<_Tp,_Tp,bool> 
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x == __y; }
 };
 
-/// One of the @link s20_3_3_comparisons comparison functors @endlink.
+/// One of the @link s20_3_3_comparisons comparison functors@endlink.
 template <class _Tp>
 struct not_equal_to : public binary_function<_Tp,_Tp,bool> 
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x != __y; }
 };
 
-/// One of the @link s20_3_3_comparisons comparison functors @endlink.
+/// One of the @link s20_3_3_comparisons comparison functors@endlink.
 template <class _Tp>
 struct greater : public binary_function<_Tp,_Tp,bool> 
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x > __y; }
 };
 
-/// One of the @link s20_3_3_comparisons comparison functors @endlink.
+/// One of the @link s20_3_3_comparisons comparison functors@endlink.
 template <class _Tp>
 struct less : public binary_function<_Tp,_Tp,bool> 
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x < __y; }
 };
 
-/// One of the @link s20_3_3_comparisons comparison functors @endlink.
+/// One of the @link s20_3_3_comparisons comparison functors@endlink.
 template <class _Tp>
 struct greater_equal : public binary_function<_Tp,_Tp,bool>
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x >= __y; }
 };
 
-/// One of the @link s20_3_3_comparisons comparison functors @endlink.
+/// One of the @link s20_3_3_comparisons comparison functors@endlink.
 template <class _Tp>
 struct less_equal : public binary_function<_Tp,_Tp,bool> 
 {
@@ -237,21 +237,21 @@ struct less_equal : public binary_function<_Tp,_Tp,bool>
  *
  *  @{
 */
-/// One of the @link s20_3_4_logical Boolean operations functors @endlink.
+/// One of the @link s20_3_4_logical Boolean operations functors@endlink.
 template <class _Tp>
 struct logical_and : public binary_function<_Tp,_Tp,bool>
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x && __y; }
 };
 
-/// One of the @link s20_3_4_logical Boolean operations functors @endlink.
+/// One of the @link s20_3_4_logical Boolean operations functors@endlink.
 template <class _Tp>
 struct logical_or : public binary_function<_Tp,_Tp,bool>
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x || __y; }
 };
 
-/// One of the @link s20_3_4_logical Boolean operations functors @endlink.
+/// One of the @link s20_3_4_logical Boolean operations functors@endlink.
 template <class _Tp>
 struct logical_not : public unary_function<_Tp,bool>
 {
@@ -286,7 +286,7 @@ struct logical_not : public unary_function<_Tp,bool>
  *
  *  @{
 */
-/// One of the @link s20_3_5_negators negation functors @endlink.
+/// One of the @link s20_3_5_negators negation functors@endlink.
 template <class _Predicate>
 class unary_negate
   : public unary_function<typename _Predicate::argument_type, bool> {
@@ -299,7 +299,7 @@ public:
   }
 };
 
-/// One of the @link s20_3_5_negators negation functors @endlink.
+/// One of the @link s20_3_5_negators negation functors@endlink.
 template <class _Predicate>
 inline unary_negate<_Predicate> 
 not1(const _Predicate& __pred)
@@ -307,7 +307,7 @@ not1(const _Predicate& __pred)
   return unary_negate<_Predicate>(__pred);
 }
 
-/// One of the @link s20_3_5_negators negation functors @endlink.
+/// One of the @link s20_3_5_negators negation functors@endlink.
 template <class _Predicate> 
 class binary_negate 
   : public binary_function<typename _Predicate::first_argument_type,
@@ -324,7 +324,7 @@ public:
   }
 };
 
-/// One of the @link s20_3_5_negators negation functors @endlink.
+/// One of the @link s20_3_5_negators negation functors@endlink.
 template <class _Predicate>
 inline binary_negate<_Predicate> 
 not2(const _Predicate& __pred)
@@ -364,7 +364,7 @@ not2(const _Predicate& __pred)
  *
  *  @{
 */
-/// One of the @link s20_3_6_binder binder functors @endlink.
+/// One of the @link s20_3_6_binder binder functors@endlink.
 template <class _Operation> 
 class binder1st
   : public unary_function<typename _Operation::second_argument_type,
@@ -389,7 +389,7 @@ public:
 #endif
 };
 
-/// One of the @link s20_3_6_binder binder functors @endlink.
+/// One of the @link s20_3_6_binder binder functors@endlink.
 template <class _Operation, class _Tp>
 inline binder1st<_Operation> 
 bind1st(const _Operation& __fn, const _Tp& __x) 
@@ -398,7 +398,7 @@ bind1st(const _Operation& __fn, const _Tp& __x)
   return binder1st<_Operation>(__fn, _Arg1_type(__x));
 }
 
-/// One of the @link s20_3_6_binder binder functors @endlink.
+/// One of the @link s20_3_6_binder binder functors@endlink.
 template <class _Operation> 
 class binder2nd
   : public unary_function<typename _Operation::first_argument_type,
@@ -423,7 +423,7 @@ public:
 #endif
 };
 
-/// One of the @link s20_3_6_binder binder functors @endlink.
+/// One of the @link s20_3_6_binder binder functors@endlink.
 template <class _Operation, class _Tp>
 inline binder2nd<_Operation> 
 bind2nd(const _Operation& __fn, const _Tp& __x) 
@@ -535,7 +535,7 @@ compose2(const _Operation1& __fn1, const _Operation2& __fn2,
  *
  *  @{
 */
-/// One of the @link s20_3_7_adaptors adaptors for function pointers @endlink.
+/// One of the @link s20_3_7_adaptors adaptors for function pointers@endlink.
 template <class _Arg, class _Result>
 class pointer_to_unary_function : public unary_function<_Arg, _Result> {
 protected:
@@ -546,14 +546,14 @@ public:
   _Result operator()(_Arg __x) const { return _M_ptr(__x); }
 };
 
-/// One of the @link s20_3_7_adaptors adaptors for function pointers @endlink.
+/// One of the @link s20_3_7_adaptors adaptors for function pointers@endlink.
 template <class _Arg, class _Result>
 inline pointer_to_unary_function<_Arg, _Result> ptr_fun(_Result (*__x)(_Arg))
 {
   return pointer_to_unary_function<_Arg, _Result>(__x);
 }
 
-/// One of the @link s20_3_7_adaptors adaptors for function pointers @endlink.
+/// One of the @link s20_3_7_adaptors adaptors for function pointers@endlink.
 template <class _Arg1, class _Arg2, class _Result>
 class pointer_to_binary_function : 
   public binary_function<_Arg1,_Arg2,_Result> {
@@ -568,7 +568,7 @@ public:
     }
 };
 
-/// One of the @link s20_3_7_adaptors adaptors for function pointers @endlink.
+/// One of the @link s20_3_7_adaptors adaptors for function pointers@endlink.
 template <class _Arg1, class _Arg2, class _Result>
 inline pointer_to_binary_function<_Arg1,_Arg2,_Result> 
 ptr_fun(_Result (*__x)(_Arg1, _Arg2)) {
@@ -823,7 +823,7 @@ public:
  *
  *  @{
 */
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Ret, class _Tp>
 class mem_fun_t : public unary_function<_Tp*,_Ret> {
 public:
@@ -833,7 +833,7 @@ private:
   _Ret (_Tp::*_M_f)();
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Ret, class _Tp>
 class const_mem_fun_t : public unary_function<const _Tp*,_Ret> {
 public:
@@ -843,7 +843,7 @@ private:
   _Ret (_Tp::*_M_f)() const;
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Ret, class _Tp>
 class mem_fun_ref_t : public unary_function<_Tp,_Ret> {
 public:
@@ -853,7 +853,7 @@ private:
   _Ret (_Tp::*_M_f)();
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Ret, class _Tp>
 class const_mem_fun_ref_t : public unary_function<_Tp,_Ret> {
 public:
@@ -863,7 +863,7 @@ private:
   _Ret (_Tp::*_M_f)() const;
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Ret, class _Tp, class _Arg>
 class mem_fun1_t : public binary_function<_Tp*,_Arg,_Ret> {
 public:
@@ -873,7 +873,7 @@ private:
   _Ret (_Tp::*_M_f)(_Arg);
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Ret, class _Tp, class _Arg>
 class const_mem_fun1_t : public binary_function<const _Tp*,_Arg,_Ret> {
 public:
@@ -884,7 +884,7 @@ private:
   _Ret (_Tp::*_M_f)(_Arg) const;
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Ret, class _Tp, class _Arg>
 class mem_fun1_ref_t : public binary_function<_Tp,_Arg,_Ret> {
 public:
@@ -894,7 +894,7 @@ private:
   _Ret (_Tp::*_M_f)(_Arg);
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Ret, class _Tp, class _Arg>
 class const_mem_fun1_ref_t : public binary_function<_Tp,_Arg,_Ret> {
 public:
@@ -904,7 +904,7 @@ private:
   _Ret (_Tp::*_M_f)(_Arg) const;
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Tp>
 class mem_fun_t<void, _Tp> : public unary_function<_Tp*,void> {
 public:
@@ -914,7 +914,7 @@ private:
   void (_Tp::*_M_f)();
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Tp>
 class const_mem_fun_t<void, _Tp> : public unary_function<const _Tp*,void> {
 public:
@@ -924,7 +924,7 @@ private:
   void (_Tp::*_M_f)() const;
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Tp>
 class mem_fun_ref_t<void, _Tp> : public unary_function<_Tp,void> {
 public:
@@ -934,7 +934,7 @@ private:
   void (_Tp::*_M_f)();
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Tp>
 class const_mem_fun_ref_t<void, _Tp> : public unary_function<_Tp,void> {
 public:
@@ -944,7 +944,7 @@ private:
   void (_Tp::*_M_f)() const;
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Tp, class _Arg>
 class mem_fun1_t<void, _Tp, _Arg> : public binary_function<_Tp*,_Arg,void> {
 public:
@@ -954,7 +954,7 @@ private:
   void (_Tp::*_M_f)(_Arg);
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Tp, class _Arg>
 class const_mem_fun1_t<void, _Tp, _Arg> 
   : public binary_function<const _Tp*,_Arg,void> {
@@ -965,7 +965,7 @@ private:
   void (_Tp::*_M_f)(_Arg) const;
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Tp, class _Arg>
 class mem_fun1_ref_t<void, _Tp, _Arg>
   : public binary_function<_Tp,_Arg,void> {
@@ -976,7 +976,7 @@ private:
   void (_Tp::*_M_f)(_Arg);
 };
 
-/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers@endlink.
 template <class _Tp, class _Arg>
 class const_mem_fun1_ref_t<void, _Tp, _Arg>
   : public binary_function<_Tp,_Arg,void> {
diff --git a/libstdc++-v3/include/bits/stl_heap.h b/libstdc++-v3/include/bits/stl_heap.h
index 8f4d06804cd..c19195aad39 100644
--- a/libstdc++-v3/include/bits/stl_heap.h
+++ b/libstdc++-v3/include/bits/stl_heap.h
@@ -52,8 +52,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_heap.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef _CPP_BITS_STL_HEAP_H
diff --git a/libstdc++-v3/include/bits/stl_iterator.h b/libstdc++-v3/include/bits/stl_iterator.h
index 3929f79565d..abf5e520c3f 100644
--- a/libstdc++-v3/include/bits/stl_iterator.h
+++ b/libstdc++-v3/include/bits/stl_iterator.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_iterator.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_ITERATOR_H
diff --git a/libstdc++-v3/include/bits/stl_iterator_base_funcs.h b/libstdc++-v3/include/bits/stl_iterator_base_funcs.h
index 07fc896fad8..1dda9c228ef 100644
--- a/libstdc++-v3/include/bits/stl_iterator_base_funcs.h
+++ b/libstdc++-v3/include/bits/stl_iterator_base_funcs.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_iterator_base_funcs.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_ITERATOR_BASE_FUNCS_H
diff --git a/libstdc++-v3/include/bits/stl_iterator_base_types.h b/libstdc++-v3/include/bits/stl_iterator_base_types.h
index bb6b8ead924..65aaa66f6ce 100644
--- a/libstdc++-v3/include/bits/stl_iterator_base_types.h
+++ b/libstdc++-v3/include/bits/stl_iterator_base_types.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_iterator_base_types.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_ITERATOR_BASE_TYPES_H
diff --git a/libstdc++-v3/include/bits/stl_list.h b/libstdc++-v3/include/bits/stl_list.h
index d699dcd21ac..4feaa7157bb 100644
--- a/libstdc++-v3/include/bits/stl_list.h
+++ b/libstdc++-v3/include/bits/stl_list.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_list.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_LIST_H
diff --git a/libstdc++-v3/include/bits/stl_map.h b/libstdc++-v3/include/bits/stl_map.h
index 45f3d588ade..7c00699406c 100644
--- a/libstdc++-v3/include/bits/stl_map.h
+++ b/libstdc++-v3/include/bits/stl_map.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_map.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef _CPP_BITS_STL_MAP_H
diff --git a/libstdc++-v3/include/bits/stl_multimap.h b/libstdc++-v3/include/bits/stl_multimap.h
index f812e37216f..65e264f257e 100644
--- a/libstdc++-v3/include/bits/stl_multimap.h
+++ b/libstdc++-v3/include/bits/stl_multimap.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_multimap.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_MULTIMAP_H
diff --git a/libstdc++-v3/include/bits/stl_multiset.h b/libstdc++-v3/include/bits/stl_multiset.h
index 8aa207dffb3..0ae57a6cb38 100644
--- a/libstdc++-v3/include/bits/stl_multiset.h
+++ b/libstdc++-v3/include/bits/stl_multiset.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_multiset.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_MULTISET_H
diff --git a/libstdc++-v3/include/bits/stl_numeric.h b/libstdc++-v3/include/bits/stl_numeric.h
index 65083f703f0..9bceee0a750 100644
--- a/libstdc++-v3/include/bits/stl_numeric.h
+++ b/libstdc++-v3/include/bits/stl_numeric.h
@@ -53,11 +53,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_numeric.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
-
 #ifndef _CPP_BITS_STL_NUMERIC_H
 #define _CPP_BITS_STL_NUMERIC_H 1
 
diff --git a/libstdc++-v3/include/bits/stl_pair.h b/libstdc++-v3/include/bits/stl_pair.h
index 7bb1dfdff03..10cc2e32258 100644
--- a/libstdc++-v3/include/bits/stl_pair.h
+++ b/libstdc++-v3/include/bits/stl_pair.h
@@ -54,8 +54,8 @@
  */
 
 /** @file stl_pair.h
- *  This is an internal header file, included by other STL headers.  You
- *  should not attempt to use it directly.
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_PAIR_H
diff --git a/libstdc++-v3/include/bits/stl_pthread_alloc.h b/libstdc++-v3/include/bits/stl_pthread_alloc.h
index af77be4999a..09b7d727af6 100644
--- a/libstdc++-v3/include/bits/stl_pthread_alloc.h
+++ b/libstdc++-v3/include/bits/stl_pthread_alloc.h
@@ -40,6 +40,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file stl_pthread_alloc.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_STL_PTHREAD_ALLOC_H
 #define _CPP_BITS_STL_PTHREAD_ALLOC_H 1
 
diff --git a/libstdc++-v3/include/bits/stl_queue.h b/libstdc++-v3/include/bits/stl_queue.h
index 7b2ae94e380..82e6e5972fe 100644
--- a/libstdc++-v3/include/bits/stl_queue.h
+++ b/libstdc++-v3/include/bits/stl_queue.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_queue.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_QUEUE_H
diff --git a/libstdc++-v3/include/bits/stl_raw_storage_iter.h b/libstdc++-v3/include/bits/stl_raw_storage_iter.h
index e513db55d33..58c45cd3f0c 100644
--- a/libstdc++-v3/include/bits/stl_raw_storage_iter.h
+++ b/libstdc++-v3/include/bits/stl_raw_storage_iter.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- * You should not attempt to use it directly.
+/** @file stl_raw_storage_iter.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef _CPP_BITS_STL_RAW_STORAGE_ITERATOR_H
diff --git a/libstdc++-v3/include/bits/stl_relops.h b/libstdc++-v3/include/bits/stl_relops.h
index 567edcfbb0a..d4d3d222022 100644
--- a/libstdc++-v3/include/bits/stl_relops.h
+++ b/libstdc++-v3/include/bits/stl_relops.h
@@ -53,11 +53,7 @@
  *
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
- */
-
-/**** libstdc++-v3 note:  Inclusion of this file has been removed from
+/* +++ libstdc++-v3 note:  Inclusion of this file has been removed from
  * all of the other STL headers for safety reasons, except std_utility.h.
  * For more information, see the thread of about twenty messages starting
  * with <URL:http://gcc.gnu.org/ml/libstdc++/2001-01/msg00223.html>, or the
@@ -67,6 +63,11 @@
  * Don't use them.
 */
 
+/** @file stl_relops.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_STL_RELOPS_H
 #define _CPP_BITS_STL_RELOPS_H 1
 
diff --git a/libstdc++-v3/include/bits/stl_set.h b/libstdc++-v3/include/bits/stl_set.h
index 880e5f6a95b..22dcef308a4 100644
--- a/libstdc++-v3/include/bits/stl_set.h
+++ b/libstdc++-v3/include/bits/stl_set.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_set.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_SET_H
diff --git a/libstdc++-v3/include/bits/stl_stack.h b/libstdc++-v3/include/bits/stl_stack.h
index b0bca258bc5..0352ec5368d 100644
--- a/libstdc++-v3/include/bits/stl_stack.h
+++ b/libstdc++-v3/include/bits/stl_stack.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_stack.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_STACK_H
diff --git a/libstdc++-v3/include/bits/stl_tempbuf.h b/libstdc++-v3/include/bits/stl_tempbuf.h
index f6b154f5854..cbae35a43b3 100644
--- a/libstdc++-v3/include/bits/stl_tempbuf.h
+++ b/libstdc++-v3/include/bits/stl_tempbuf.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_tempbuf.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_TEMPBUF_H
diff --git a/libstdc++-v3/include/bits/stl_threads.h b/libstdc++-v3/include/bits/stl_threads.h
index dd27422f5c0..20c3deb16fc 100644
--- a/libstdc++-v3/include/bits/stl_threads.h
+++ b/libstdc++-v3/include/bits/stl_threads.h
@@ -40,10 +40,10 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-// WARNING: This is an internal header file, included by other C++
-// standard library headers.  You should not attempt to use this header
-// file directly.
-// Stl_config.h should be included before this file.
+/** @file stl_threads.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
 
 #ifndef __SGI_STL_INTERNAL_THREADS_H
 #define __SGI_STL_INTERNAL_THREADS_H
diff --git a/libstdc++-v3/include/bits/stl_tree.h b/libstdc++-v3/include/bits/stl_tree.h
index 87dc603c6ec..b0a052e442a 100644
--- a/libstdc++-v3/include/bits/stl_tree.h
+++ b/libstdc++-v3/include/bits/stl_tree.h
@@ -55,8 +55,9 @@
  *
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_tree.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_TREE_H
diff --git a/libstdc++-v3/include/bits/stl_uninitialized.h b/libstdc++-v3/include/bits/stl_uninitialized.h
index 383e0842179..5c107a4600c 100644
--- a/libstdc++-v3/include/bits/stl_uninitialized.h
+++ b/libstdc++-v3/include/bits/stl_uninitialized.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_uninitialized.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef _CPP_BITS_STL_UNINITIALIZED_H
diff --git a/libstdc++-v3/include/bits/stl_vector.h b/libstdc++-v3/include/bits/stl_vector.h
index 4ac20ba8dbc..157d31f1dd4 100644
--- a/libstdc++-v3/include/bits/stl_vector.h
+++ b/libstdc++-v3/include/bits/stl_vector.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_vector.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_VECTOR_H
diff --git a/libstdc++-v3/include/bits/stream_iterator.h b/libstdc++-v3/include/bits/stream_iterator.h
index c6bde4edf17..4897fc36fef 100644
--- a/libstdc++-v3/include/bits/stream_iterator.h
+++ b/libstdc++-v3/include/bits/stream_iterator.h
@@ -27,6 +27,11 @@
 // invalidate any other reasons why the executable file might be covered by
 // the GNU General Public License.
 
+/** @file stream_iterator.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_STREAM_ITERATOR_H
 #define _CPP_BITS_STREAM_ITERATOR_H 1
 
diff --git a/libstdc++-v3/include/bits/streambuf_iterator.h b/libstdc++-v3/include/bits/streambuf_iterator.h
index 3f946dabe7f..2f8b4b44070 100644
--- a/libstdc++-v3/include/bits/streambuf_iterator.h
+++ b/libstdc++-v3/include/bits/streambuf_iterator.h
@@ -29,6 +29,11 @@
 
 // XXX Should specialize copy, find algorithms for streambuf iterators.
 
+/** @file streambuf_iterator.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_STREAMBUF_ITERATOR_H
 #define _CPP_BITS_STREAMBUF_ITERATOR_H 1
 
diff --git a/libstdc++-v3/include/bits/stringfwd.h b/libstdc++-v3/include/bits/stringfwd.h
index dd8bbe56c0b..5197f9703fd 100644
--- a/libstdc++-v3/include/bits/stringfwd.h
+++ b/libstdc++-v3/include/bits/stringfwd.h
@@ -31,6 +31,11 @@
 // ISO C++ 14882: 21 Strings library
 //
 
+/** @file stringfwd.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_STRINGFWD_H
 #define _CPP_BITS_STRINGFWD_H	1
 
diff --git a/libstdc++-v3/include/bits/type_traits.h b/libstdc++-v3/include/bits/type_traits.h
index ff5f5a1fb27..2471013bf61 100644
--- a/libstdc++-v3/include/bits/type_traits.h
+++ b/libstdc++-v3/include/bits/type_traits.h
@@ -41,6 +41,11 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
+/** @file type_traits.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_TYPE_TRAITS_H
 #define _CPP_BITS_TYPE_TRAITS_H 1
 
diff --git a/libstdc++-v3/include/bits/valarray_array.h b/libstdc++-v3/include/bits/valarray_array.h
index d163d0530ff..1ef10e60b01 100644
--- a/libstdc++-v3/include/bits/valarray_array.h
+++ b/libstdc++-v3/include/bits/valarray_array.h
@@ -29,6 +29,11 @@
 
 // Written by Gabriel Dos Reis <Gabriel.Dos-Reis@DPTMaths.ENS-Cachan.Fr>
 
+/** @file valarray_array.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_BITS_ARRAY_H
 #define _CPP_BITS_ARRAY_H 1
 
diff --git a/libstdc++-v3/include/bits/valarray_meta.h b/libstdc++-v3/include/bits/valarray_meta.h
index 002fe5f901b..b4c85ba7c99 100644
--- a/libstdc++-v3/include/bits/valarray_meta.h
+++ b/libstdc++-v3/include/bits/valarray_meta.h
@@ -29,6 +29,11 @@
 
 // Written by Gabriel Dos Reis <Gabriel.Dos-Reis@cmla.ens-cachan.fr>
 
+/** @file valarray_meta.h
+ *  This is an internal header file, included by other library headers.
+ *  You should not attempt to use it directly.
+ */
+
 #ifndef _CPP_VALARRAY_META_H
 #define _CPP_VALARRAY_META_H 1