2002-11-21 Phil Edwards <pme@gcc.gnu.org>

	* docs/doxygen/TODO:  Note change in clause 27 docs.
	* include/bits/basic_ios.h, include/bits/fpos.h,
	include/bits/ios_base.h, include/bits/stl_deque.h,
	include/bits/stl_iterator_base_types.h, include/std/std_fstream.h,
	include/std/std_iomanip.h, include/std/std_iosfwd.h,
	include/std/std_iostream.h, include/std/std_istream.h,
	include/std/std_ostream.h, include/std/std_sstream.h,
	include/std/std_streambuf.h:  Doxygenate all I/O entities.


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

13 files changed, 2461 insertions, 204 deletions

diff --git a/libstdc++-v3/include/bits/basic_ios.h b/libstdc++-v3/include/bits/basic_ios.h
index 13ad0f82e99..b6ef89ba8b0 100644
--- a/libstdc++-v3/include/bits/basic_ios.h
+++ b/libstdc++-v3/include/bits/basic_ios.h
@@ -43,115 +43,282 @@
 namespace std 
 {
   // 27.4.5  Template class basic_ios
+  /**
+   *  @brief  Virtual base class for all stream classes.
+   *
+   *  Most of the member functions called dispatched on stream objects
+   *  (e.g., @c std::cout.foo(bar);) are consolidated in this class.
+  */
   template<typename _CharT, typename _Traits>
     class basic_ios : public ios_base
     {
     public:
-      // Types:
-      typedef _CharT 				char_type;
-      typedef typename _Traits::int_type 	int_type;
-      typedef typename _Traits::pos_type 	pos_type;
-      typedef typename _Traits::off_type 	off_type;
-      typedef _Traits 				traits_type;
-
-      // Non-standard Types:
-      typedef ctype<_CharT>           			__ctype_type;
-      typedef ostreambuf_iterator<_CharT, _Traits>      __ostreambuf_iter;
-      typedef num_put<_CharT, __ostreambuf_iter>        __numput_type;
-      typedef istreambuf_iterator<_CharT, _Traits>	__istreambuf_iter;
-      typedef num_get<_CharT, __istreambuf_iter>        __numget_type;
+      //@{
+      /**
+       *  These are standard types.  They permit a standardized way of
+       *  referring to names of (or names dependant on) the template
+       *  parameters, which are specific to the implementation.
+      */
+      typedef _CharT                                 char_type;
+      typedef typename _Traits::int_type             int_type;
+      typedef typename _Traits::pos_type             pos_type;
+      typedef typename _Traits::off_type             off_type;
+      typedef _Traits                                traits_type;
+      //@}
+
+      //@{
+      /**
+       *  @if maint
+       *  These are non-standard types.
+       *  @endif
+      */
+      typedef ctype<_CharT>                          __ctype_type;
+      typedef ostreambuf_iterator<_CharT, _Traits>   __ostreambuf_iter;
+      typedef num_put<_CharT, __ostreambuf_iter>     __numput_type;
+      typedef istreambuf_iterator<_CharT, _Traits>   __istreambuf_iter;
+      typedef num_get<_CharT, __istreambuf_iter>     __numget_type;
+      //@}
       
       // Data members:
     protected:
-      basic_ostream<_CharT, _Traits>* 	_M_tie;
-      mutable char_type 		_M_fill;
-      mutable bool			_M_fill_init;
-      basic_streambuf<_CharT, _Traits>* _M_streambuf;
+      basic_ostream<_CharT, _Traits>*                _M_tie;
+      mutable char_type                              _M_fill;
+      mutable bool                                   _M_fill_init;
+      basic_streambuf<_CharT, _Traits>*              _M_streambuf;
 
       // Cached use_facet<ctype>, which is based on the current locale info.
-      const __ctype_type*		_M_fctype;      
+      const __ctype_type*                            _M_fctype;      
       // From ostream.
-      const __numput_type* 		_M_fnumput;
+      const __numput_type*                           _M_fnumput;
       // From istream.
-      const __numget_type* 		_M_fnumget;
+      const __numget_type*                           _M_fnumget;
 
     public:
+      //@{
+      /**
+       *  @brief  The quick-and-easy status check.
+       *
+       *  This allows you to write constructs such as
+       *  "if (!a_stream) ..." and "while (a_stream) ..."
+      */
       operator void*() const 
       { return this->fail() ? 0 : const_cast<basic_ios*>(this); }
 
       bool 
       operator!() const 
       { return this->fail(); }
-
+      //@}
+
+      /**
+       *  @brief  Returns the error state of the stream buffer.
+       *  @return  A bit pattern (well, isn't everything?)
+       *
+       *  See std::ios_base::iostate for the possible bit values.  Most
+       *  users will call one of the interpreting wrappers, e.g., good().
+      */
       iostate 
       rdstate() const 
       { return _M_streambuf_state; }
 
+      /**
+       *  @brief  [Re]sets the error state.
+       *  @param  state  The new state flag(s) to set.
+       *
+       *  See std::ios_base::iostate for the possible bit values.  Most
+       *  users will not need to pass an argument.
+      */
       void 
       clear(iostate __state = goodbit);
 
+      /**
+       *  @brief  Sets additional flags in the error state.
+       *  @param  state  The additional state flag(s) to set.
+       *
+       *  See std::ios_base::iostate for the possible bit values.
+      */
       void 
       setstate(iostate __state) 
       { this->clear(this->rdstate() | __state); }
 
+      /**
+       *  @brief  Fast error checking.
+       *  @return  True if no error flags are set.
+       *
+       *  A wrapper around rdstate.
+      */
       bool 
       good() const 
       { return this->rdstate() == 0; }
 
+      /**
+       *  @brief  Fast error checking.
+       *  @return  True if the eofbit is set.
+       *
+       *  Note that other iostate flags may also be set.
+      */
       bool 
       eof() const 
       { return (this->rdstate() & eofbit) != 0; }
 
+      /**
+       *  @brief  Fast error checking.
+       *  @return  True if either the badbit or the failbit is set.
+       *
+       *  Checking the badbit in fail() is historical practice.
+       *  Note that other iostate flags may also be set.
+      */
       bool 
       fail() const 
       { return (this->rdstate() & (badbit | failbit)) != 0; }
 
+      /**
+       *  @brief  Fast error checking.
+       *  @return  True if the badbit is set.
+       *
+       *  Note that other iostate flags may also be set.
+      */
       bool 
       bad() const 
       { return (this->rdstate() & badbit) != 0; }
 
+      /**
+       *  @brief  Throwing exceptions on errors.
+       *  @return  The current exceptions mask.
+       *
+       *  This changes nothing in the stream.  See the one-argument version
+       *  of exceptions(iostate) for the meaning of the return value.
+      */
       iostate 
       exceptions() const 
       { return _M_exception; }
 
+      /**
+       *  @brief  Throwing exceptions on errors.
+       *  @param  except  The new exceptions mask.
+       *
+       *  By default, error flags are set silently.  You can set an
+       *  exceptions mask for each stream; if a bit in the mask becomes set
+       *  in the error flags, then an exception of type
+       *  std::ios_base::failure is thrown.
+       *
+       *  If the error flage is already set when the exceptions mask is
+       *  added, the exception is immediately thrown.  Try running the
+       *  following under GCC 3.1 or later:
+       *  @code
+       *  #include <iostream>
+       *  #include <fstream>
+       *  #include <exception>
+       *  
+       *  int main()
+       *  {
+       *      std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
+       *  
+       *      std::ifstream f ("/etc/motd");
+       *  
+       *      std::cerr << "Setting badbit\n";
+       *      f.setstate (std::ios_base::badbit);
+       *  
+       *      std::cerr << "Setting exception mask\n";
+       *      f.exceptions (std::ios_base::badbit);
+       *  }
+       *  @endcode
+      */
       void 
       exceptions(iostate __except) 
       { 
-	_M_exception = __except; 
-	this->clear(_M_streambuf_state); 
+        _M_exception = __except; 
+        this->clear(_M_streambuf_state); 
       }
 
       // Constructor/destructor:
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  The parameter is passed by derived streams.
+      */
       explicit 
       basic_ios(basic_streambuf<_CharT, _Traits>* __sb) : ios_base() 
       { this->init(__sb); }
 
+      /**
+       *  @brief  Empty.
+       *
+       *  The destructor does nothing.  More specifically, it does not
+       *  destroy the streambuf held by rdbuf().
+      */
       virtual 
       ~basic_ios() { }
       
       // Members:
+      /**
+       *  @brief  Fetches the current @e tied stream.
+       *  @return  A pointer to the tied stream, or NULL if the stream is
+       *           not tied.
+       *
+       *  A stream may be @e tied (or synchronized) to a second output
+       *  stream.  When this stream performs any I/O, the tied stream is
+       *  first flushed.  For example, @c std::cin is tied to @c std::cout.
+      */
       basic_ostream<_CharT, _Traits>*
       tie() const      
       { return _M_tie; }
 
+      /**
+       *  @brief  Ties this stream to an output stream.
+       *  @param  tiestr  The output stream.
+       *  @return  The previously tied output stream, or NULL if the stream
+       *           was not tied.
+       *
+       *  This sets up a new tie; see tie() for more.
+      */
       basic_ostream<_CharT, _Traits>*
       tie(basic_ostream<_CharT, _Traits>* __tiestr)
       {
-	basic_ostream<_CharT, _Traits>* __old = _M_tie;
-	_M_tie = __tiestr;
-	return __old;
+        basic_ostream<_CharT, _Traits>* __old = _M_tie;
+        _M_tie = __tiestr;
+        return __old;
       }
 
+      /**
+       *  @brief  Accessing the underlying buffer.
+       *  @return  The current stream buffer.
+       *
+       *  This does not change the state of the stream.
+      */
       basic_streambuf<_CharT, _Traits>*
       rdbuf() const    
       { return _M_streambuf; }
 
+      /**
+       *  @brief  Changing the underlying buffer.
+       *  @param  sb  The new stream buffer.
+       *  @return  The previous stream buffer.
+       *
+       *  Associates a new buffer with the current stream, and clears the
+       *  error state.
+       *
+       *  Due to historical accidents which the LWG refuses to correct, the
+       *  I/O library suffers from a design error:  this function is hidden
+       *  in derived classes by overrides of the zero-argument @c rdbuf(),
+       *  which is non-virtual for hysterical raisins.  As a result, you
+       *  must use explicit qualifications to access this function via any
+       *  derived class.
+      */
       basic_streambuf<_CharT, _Traits>* 
       rdbuf(basic_streambuf<_CharT, _Traits>* __sb);
 
+      /**
+       *  @doctodo
+      */
       basic_ios&
       copyfmt(const basic_ios& __rhs);
 
+      /**
+       *  @brief  Retreives the "empty" character.
+       *  @return  The current fill character.
+       *
+       *  It defaults to a space (' ') in the current locale.
+      */
       char_type 
       fill() const 
       {
@@ -163,6 +330,15 @@ namespace std
 	return _M_fill; 
       }
 
+      /**
+       *  @brief  Sets a new "empty" character.
+       *  @param  ch  The new character.
+       *  @return  The previous fill character.
+       *
+       *  The fill character is used to fill out space when P+ characters
+       *  have been requested (e.g., via setw), Q characters are actually
+       *  used, and Q<P.  It defaults to a space (' ') in the current locale.
+      */
       char_type 
       fill(char_type __ch)
       {
@@ -172,20 +348,75 @@ namespace std
       }
 
       // Locales:
+      /**
+       *  @brief  Moves to a new locale.
+       *  @param  loc  The new locale.
+       *  @return  The previous locale.
+       *
+       *  Calls @c ios_base::imbue(loc), and if a stream buffer is associated
+       *  with this stream, calls that buffer's @c pubimbue(loc).
+       *
+       *  Additional l10n notes are at
+       *  http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
+      */
       locale 
       imbue(const locale& __loc);
 
+      /**
+       *  @brief  Squeezes characters.
+       *  @param  c  The character to narrow.
+       *  @param  dfault  The character to narrow.
+       *  @return  The narrowed character.
+       *
+       *  Maps a character of @c char_type to a character of @c char,
+       *  if possible.
+       *
+       *  Returns the result of
+       *  @code
+       *    std::use_facet< ctype<char_type> >(getloc()).narrow(c,dfault)
+       *  @endcode
+       *
+       *  Additional l10n notes are at
+       *  http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
+      */
       char 
       narrow(char_type __c, char __dfault) const;
 
+      /**
+       *  @brief  Widens characters.
+       *  @param  c  The character to widen.
+       *  @return  The widened character.
+       *
+       *  Maps a character of @c char to a character of @c char_type.
+       *
+       *  Returns the result of
+       *  @code
+       *    std::use_facet< ctype<char_type> >(getloc()).widen(c)
+       *  @endcode
+       *
+       *  Additional l10n notes are at
+       *  http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
+      */
       char_type 
       widen(char __c) const;
      
     protected:
       // 27.4.5.1  basic_ios constructors
+      /**
+       *  @brief  Empty.
+       *
+       *  The default constructor does nothing and is not normally
+       *  accessible to users.
+      */
       basic_ios() : ios_base() 
       { }
 
+      /**
+       *  @brief  All setup is performed here.
+       *
+       *  This is called from the public constructor.  It is not virtual and
+       *  cannot be redefined.
+      */
       void 
       init(basic_streambuf<_CharT, _Traits>* __sb);
 
diff --git a/libstdc++-v3/include/bits/fpos.h b/libstdc++-v3/include/bits/fpos.h
index 279e0ab16ba..5432527421a 100644
--- a/libstdc++-v3/include/bits/fpos.h
+++ b/libstdc++-v3/include/bits/fpos.h
@@ -48,7 +48,10 @@ namespace std
 {
   // 27.4.1  Types
 
-  // 27.4.3  Template class fpos
+  // [27.4.3] template class fpos
+  /**
+   *  @doctodo
+  */
   template<typename _StateT>
     class fpos
     {
@@ -113,9 +116,10 @@ namespace std
       _M_position(streamoff __off)  { _M_off = __off; }
     };
 
-  // 27.2, paragraph 10 about fpos/char_traits circularity
+  /// 27.2, paragraph 10 about fpos/char_traits circularity
   typedef fpos<mbstate_t> 		streampos;
 #  ifdef _GLIBCPP_USE_WCHAR_T
+  /// 27.2, paragraph 10 about fpos/char_traits circularity
   typedef fpos<mbstate_t> 		wstreampos;
 #  endif
 }  // namespace std
diff --git a/libstdc++-v3/include/bits/ios_base.h b/libstdc++-v3/include/bits/ios_base.h
index 2cfe4134c92..1f085d9e4e7 100644
--- a/libstdc++-v3/include/bits/ios_base.h
+++ b/libstdc++-v3/include/bits/ios_base.h
@@ -145,11 +145,20 @@ namespace std
   enum _Ios_Seekdir { _M_ios_seekdir_end = 1L << 16 };
 
   // 27.4.2  Class ios_base
+  /**
+   *  @brief  The very top of the I/O class hierarchy.
+   *
+   *  This class defines everything that can be defined about I/O that does
+   *  not depend on the type of characters being input or output.  Most
+   *  people will only see @c ios_base when they need to specify the full
+   *  name of the various I/O flags (e.g., the openmodes).
+  */
   class ios_base
   {
   public:
     
     // 27.4.2.1.1  Class ios_base::failure
+    /// These are thrown to indicate problems.  Doc me.
     class failure : public exception
     {
     public:
@@ -173,47 +182,148 @@ namespace std
     };
 
     // 27.4.2.1.2  Type ios_base::fmtflags
+    /**
+     *  @brief This is a bitmask type.
+     *
+     *  @c "_Ios_Fmtflags" is implementation-defined, but it is valid to
+     *  perform bitwise operations on these values and expect the Right
+     *  Thing to happen.  Defined objects of type fmtflags are:
+     *  - boolalpha
+     *  - dec
+     *  - fixed
+     *  - hex
+     *  - internal
+     *  - left
+     *  - oct
+     *  - right
+     *  - scientific
+     *  - showbase
+     *  - showpoint
+     *  - showpos
+     *  - skipws
+     *  - unitbuf
+     *  - uppercase
+     *  - adjustfield
+     *  - basefield
+     *  - floatfield
+    */
     typedef _Ios_Fmtflags fmtflags;
-    // 27.4.2.1.2  Type fmtflags
+    /// Insert/extract @c bool in alphabetic rather than numeric format.
     static const fmtflags boolalpha =   fmtflags(__ios_flags::_S_boolalpha);
+    /// Converts integer input or generates integer output in decimal base.
     static const fmtflags dec =         fmtflags(__ios_flags::_S_dec);
+    /// Generate floating-point output in fixed-point notation.
     static const fmtflags fixed =       fmtflags(__ios_flags::_S_fixed);
+    /// Converts integer input or generates integer output in hexadecimal base.
     static const fmtflags hex =         fmtflags(__ios_flags::_S_hex);
+    /// Adds fill characters at a designated internal point in certain
+    /// generated output, or identical to @c right if no such point is
+    /// designated.
     static const fmtflags internal =    fmtflags(__ios_flags::_S_internal);
+    /// Adds fill characters on the right (final positions) of certain
+    /// generated output.  (I.e., the thing you print is flush left.)
     static const fmtflags left =        fmtflags(__ios_flags::_S_left);
+    /// Converts integer input or generates integer output in octal base.
     static const fmtflags oct =         fmtflags(__ios_flags::_S_oct);
+    /// Adds fill characters on the left (initial positions) of certain
+    /// generated output.  (I.e., the thing you print is flush right.)
     static const fmtflags right =       fmtflags(__ios_flags::_S_right);
+    /// Generates floating-point output in scientific notation.
     static const fmtflags scientific =  fmtflags(__ios_flags::_S_scientific);
+    /// Generates a prefix indicating the numeric base of generated integer
+    /// output.
     static const fmtflags showbase =    fmtflags(__ios_flags::_S_showbase);
+    /// Generates a decimal-point character unconditionally in generated
+    /// floating-point output.
     static const fmtflags showpoint =   fmtflags(__ios_flags::_S_showpoint);
+    /// Generates a + sign in non-negative generated numeric output.
     static const fmtflags showpos =     fmtflags(__ios_flags::_S_showpos);
+    /// Skips leading white space before certain input operations.
     static const fmtflags skipws =      fmtflags(__ios_flags::_S_skipws);
+    /// Flushes output after each output operation.
     static const fmtflags unitbuf =     fmtflags(__ios_flags::_S_unitbuf);
+    /// Replaces certain lowercase letters with their uppercase equivalents
+    /// in generated output.
     static const fmtflags uppercase =   fmtflags(__ios_flags::_S_uppercase);
+    /// A mask of left|right|internal.  Useful for the 2-arg form of @c setf.
     static const fmtflags adjustfield = fmtflags(__ios_flags::_S_adjustfield);
+    /// A mask of dec|oct|hex.  Useful for the 2-arg form of @c setf.
     static const fmtflags basefield =   fmtflags(__ios_flags::_S_basefield);
+    /// A mask of scientific|fixed.  Useful for the 2-arg form of @c setf.
     static const fmtflags floatfield =  fmtflags(__ios_flags::_S_floatfield);
 
     // 27.4.2.1.3  Type ios_base::iostate
+    /**
+     *  @brief This is a bitmask type.
+     *
+     *  @c "_Ios_Iostate" is implementation-defined, but it is valid to
+     *  perform bitwise operations on these values and expect the Right
+     *  Thing to happen.  Defined objects of type iostate are:
+     *  - badbit
+     *  - eofbit
+     *  - failbit
+     *  - goodbit
+    */
     typedef _Ios_Iostate iostate;
+    /// Indicates a loss of integrity in an input or output sequence (such
+    /// as an irrecoverable read error from a file).
     static const iostate badbit =  	iostate(__ios_flags::_S_badbit);
+    /// Indicates that an input operation reached the end of an input sequence.
     static const iostate eofbit =  	iostate(__ios_flags::_S_eofbit);
+    /// Indicates that an input operation failed to read the expected
+    /// characters, or that an output operation failed to generate the
+    /// desired characters.
     static const iostate failbit = 	iostate(__ios_flags::_S_failbit);
+    /// Indicates all is well.
     static const iostate goodbit = 	iostate(0);
 
-    // 27.4.2.1.4  Type openmode
+    // 27.4.2.1.4  Type ios_base::openmode
+    /**
+     *  @brief This is a bitmask type.
+     *
+     *  @c "_Ios_Openmode" is implementation-defined, but it is valid to
+     *  perform bitwise operations on these values and expect the Right
+     *  Thing to happen.  Defined objects of type openmode are:
+     *  - app
+     *  - ate
+     *  - binary
+     *  - in
+     *  - out
+     *  - trunc
+    */
     typedef _Ios_Openmode openmode;
+    /// Seek to end before each write.
     static const openmode app =    	openmode(__ios_flags::_S_app);
+    /// Open and seek to end immediately after opening.
     static const openmode ate =    	openmode(__ios_flags::_S_ate);
+    /// Perform input and output in binary mode (as opposed to text mode).
+    /// This is probably not what you think it is; see
+    /// http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#3 and
+    /// http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#7 for more.
     static const openmode binary = 	openmode(__ios_flags::_S_bin);
+    /// Open for input.  Default for @c ifstream and fstream.
     static const openmode in =     	openmode(__ios_flags::_S_in);
+    /// Open for output.  Default for @c ofstream and fstream.
     static const openmode out =    	openmode(__ios_flags::_S_out);
+    /// Open for input.  Default for @c ofstream.
     static const openmode trunc =  	openmode(__ios_flags::_S_trunc);
 
-    // 27.4.2.1.5  Type seekdir
+    // 27.4.2.1.5  Type ios_base::seekdir
+    /**
+     *  @brief This is an enumerated type.
+     *
+     *  @c "_Ios_Seekdir" is implementation-defined.  Defined values
+     *  of type seekdir are:
+     *  - beg
+     *  - cur, equivalent to @c SEEK_CUR in the C standard library.
+     *  - end, equivalent to @c SEEK_END in the C standard library.
+    */
     typedef _Ios_Seekdir seekdir;
+    /// Request a seek relative to the beginning of the stream.
     static const seekdir beg = 		seekdir(0);
+    /// Request a seek relative to the current position within the sequence.
     static const seekdir cur = 		seekdir(SEEK_CUR);
+    /// Request a seek relative to the current end of the sequence.
     static const seekdir end = 		seekdir(SEEK_END);
 
 #ifdef _GLIBCPP_DEPRECATED
@@ -227,6 +337,9 @@ namespace std
 #endif
 
     // Callbacks;
+    /**
+     *  @doctodo
+    */
     enum event
     {
       erase_event,
@@ -234,18 +347,30 @@ namespace std
       copyfmt_event
     };
 
+    /**
+     *  @doctodo
+    */
     typedef void (*event_callback) (event, ios_base&, int);
 
+    /**
+     *  @doctodo
+    */
     void 
     register_callback(event_callback __fn, int __index);
 
   protected:
-    // Data Members
+    //@{
+    /**
+     *  @if maint
+     *  ios_base data members (doc me)
+     *  @endif
+    */
     streamsize 		_M_precision;
     streamsize 		_M_width;
     fmtflags 		_M_flags;
     iostate 		_M_exception;
     iostate 	       	_M_streambuf_state;
+    //@}
 
     // 27.4.2.6  Members for callbacks
     // 27.4.2.6  ios_base callbacks
@@ -329,10 +454,21 @@ namespace std
       static bool	_S_synced_with_stdio;
     };
 
-    // Fmtflags state:
+    // [27.4.2.2] fmtflags state functions
+    /**
+     *  @brief  Access to format flags.
+     *  @return  The format control flags for both input and output.
+    */
     inline fmtflags 
     flags() const { return _M_flags; }
 
+    /**
+     *  @brief  Setting new format flags all at once.
+     *  @param  fmtfl  The new flags to set.
+     *  @return  The previous format control flags.
+     *
+     *  This function overwrites all the format flags with @a fmtfl.
+    */
     inline fmtflags 
     flags(fmtflags __fmtfl)
     { 
@@ -341,6 +477,14 @@ namespace std
       return __old; 
     }
 
+    /**
+     *  @brief  Setting new format flags.
+     *  @param  fmtfl  Additional flags to set.
+     *  @return  The previous format control flags.
+     *
+     *  This function sets additional flags in format control.  Flags that
+     *  were previously set remain set.
+    */
     inline fmtflags 
     setf(fmtflags __fmtfl)
     { 
@@ -349,6 +493,15 @@ namespace std
       return __old; 
     }
 
+    /**
+     *  @brief  Setting new format flags.
+     *  @param  fmtfl  Additional flags to set.
+     *  @param  mask  The flags mask for @a fmtfl.
+     *  @return  The previous format control flags.
+     *
+     *  This function clears @a mask in the format flags, then sets
+     *  @a fmtfl @c & @a mask.  An example mask is @c ios_base::adjustfield.
+    */
     inline fmtflags 
     setf(fmtflags __fmtfl, fmtflags __mask)
     {
@@ -358,12 +511,32 @@ namespace std
       return __old;
     }
 
+    /**
+     *  @brief  Clearing format flags.
+     *  @param  mask  The flags to unset.
+     *
+     *  This function clears @a mask in the format flags.
+    */
     inline void 
     unsetf(fmtflags __mask) { _M_flags &= ~__mask; }
 
+    /**
+     *  @brief  Flags access.
+     *  @return  The precision to generate on certain output operations.
+     *
+     *  @if maint
+     *  Be careful if you try to give a definition of "precision" here; see
+     *  DR 189.
+     *  @endif
+    */
     inline streamsize 
     precision() const { return _M_precision; }
 
+    /**
+     *  @brief  Changing flags.
+     *  @param  prec  The new precision value.
+     *  @return  The previous value of precision().
+    */
     inline streamsize 
     precision(streamsize __prec)
     { 
@@ -372,9 +545,20 @@ namespace std
       return __old; 
     }
 
+    /**
+     *  @brief  Flags access.
+     *  @return  The minimum field width to generate on output operations.
+     *
+     *  "Minimum field width" refers to the number of characters.
+    */
     inline streamsize 
     width() const { return _M_width; }
 
+    /**
+     *  @brief  Changing flags.
+     *  @param  wide  The new width value.
+     *  @return  The previous value of width().
+    */
     inline streamsize 
     width(streamsize __wide)
     { 
@@ -383,20 +567,53 @@ namespace std
       return __old; 
     }
 
+    // [27.4.2.4] ios_base static members
+    /**
+     *  @brief  Interaction with the standard C I/O objects.
+     *  @param  sync  Whether to synchronize or not.
+     *  @return  True if the standard streams were previously synchronized.
+     *
+     *  The synchronization referred to is @e only that between the standard
+     *  C facilities (e.g., stdout) and the standard C++ objects (e.g.,
+     *  cout).  User-declared streams are unaffected.  See
+     *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#8 for more.
+    */
     static bool 
     sync_with_stdio(bool __sync = true);
 
-    // Locales:
+    // [27.4.2.3] ios_base locale functions
+    /**
+     *  @brief  Setting a new locale.
+     *  @param  loc  The new locale.
+     *  @return  The previous locale.
+     *
+     *  Sets the new locale for this stream, and
+     *  [XXX does something with callbacks].
+    */
     locale 
     imbue(const locale& __loc);
 
+    /**
+     *  @brief  Locale access
+     *  @return  The locale currently in effect.
+     *
+     *  If @c imbue(loc) has previously been called, then this function
+     *  returns @c loc.  Otherwise, it returns a copy of @c std::locale(),
+     *  the global C++ locale.
+    */
     inline locale 
     getloc() const { return _M_ios_locale; }
 
-    // Storage:
+    // [27.4.2.5] ios_base storage functions
+    /**
+     *  @doctodo
+    */
     static int 
     xalloc() throw();
 
+    /**
+     *  @doctodo
+    */
     inline long& 
     iword(int __ix)
     {
@@ -405,6 +622,9 @@ namespace std
       return __word._M_iword;
     }
 
+    /**
+     *  @doctodo
+    */
     inline void*& 
     pword(int __ix)
     {
@@ -414,6 +634,10 @@ namespace std
     }
 
     // Destructor
+    /**
+     *  Destroys local storage and
+     *  [XXX does something with callbacks].
+    */
     virtual ~ios_base();
 
   protected:
@@ -429,7 +653,8 @@ namespace std
 #endif
   };
  
-  // 27.4.5.1 fmtflags manipulators:
+  // [27.4.5.1] fmtflags manipulators
+  /// Calls base.setf(ios_base::boolalpha).
   inline ios_base& 
   boolalpha(ios_base& __base)
   {
@@ -437,6 +662,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.unsetf(ios_base::boolalpha).
   inline ios_base& 
   noboolalpha(ios_base& __base)
   {
@@ -444,6 +670,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.setf(ios_base::showbase).
   inline ios_base& 
   showbase(ios_base& __base)
   {
@@ -451,6 +678,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.unsetf(ios_base::showbase).
   inline ios_base& 
   noshowbase(ios_base& __base)
   {
@@ -458,6 +686,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.setf(ios_base::showpoint).
   inline ios_base& 
   showpoint(ios_base& __base)
   {
@@ -465,6 +694,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.unsetf(ios_base::showpoint).
   inline ios_base& 
   noshowpoint(ios_base& __base)
   {
@@ -472,6 +702,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.setf(ios_base::showpos).
   inline ios_base& 
   showpos(ios_base& __base)
   {
@@ -479,6 +710,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.unsetf(ios_base::showpos).
   inline ios_base& 
   noshowpos(ios_base& __base)
   {
@@ -486,6 +718,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.setf(ios_base::skipws).
   inline ios_base& 
   skipws(ios_base& __base)
   {
@@ -493,6 +726,7 @@ namespace std
     return __base;
   }
   
+  /// Calls base.unsetf(ios_base::skipws).
   inline ios_base& 
   noskipws(ios_base& __base)
   {
@@ -500,6 +734,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.setf(ios_base::uppercase).
   inline ios_base& 
   uppercase(ios_base& __base)
   {
@@ -507,6 +742,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.unsetf(ios_base::uppercase).
   inline ios_base& 
   nouppercase(ios_base& __base)
   {
@@ -514,6 +750,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.setf(ios_base::unitbuf).
   inline ios_base& 
   unitbuf(ios_base& __base)
   {
@@ -521,6 +758,7 @@ namespace std
      return __base;
   }
 
+  /// Calls base.unsetf(ios_base::unitbuf).
   inline ios_base& 
   nounitbuf(ios_base& __base)
   {
@@ -528,7 +766,8 @@ namespace std
      return __base;    
   }
 
-  // 27.4.5.2 adjustfield anipulators:
+  // [27.4.5.2] adjustfield anipulators
+  /// Calls base.setf(ios_base::internal, ios_base::adjustfield).
   inline ios_base& 
   internal(ios_base& __base)
   {
@@ -536,6 +775,7 @@ namespace std
      return __base;    
   }
 
+  /// Calls base.setf(ios_base::left, ios_base::adjustfield).
   inline ios_base& 
   left(ios_base& __base)
   {
@@ -543,6 +783,7 @@ namespace std
     return __base;
   }
   
+  /// Calls base.setf(ios_base::right, ios_base::adjustfield).
   inline ios_base& 
   right(ios_base& __base)
   {
@@ -550,7 +791,8 @@ namespace std
     return __base;
   }
   
-  // 27.4.5.3 basefield anipulators:
+  // [27.4.5.3] basefield anipulators
+  /// Calls base.setf(ios_base::dec, ios_base::basefield).
   inline ios_base& 
   dec(ios_base& __base)
   {
@@ -558,6 +800,7 @@ namespace std
     return __base;
   }
   
+  /// Calls base.setf(ios_base::hex, ios_base::basefield).
   inline ios_base& 
   hex(ios_base& __base)
   {
@@ -565,6 +808,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.setf(ios_base::oct, ios_base::basefield).
   inline ios_base& 
   oct(ios_base& __base)
   {
@@ -572,7 +816,8 @@ namespace std
     return __base;
   }
   
-  // 27.4.5.4 floatfield anipulators:
+  // [27.4.5.4] floatfield anipulators
+  /// Calls base.setf(ios_base::fixed, ios_base::floatfield).
   inline ios_base& 
   fixed(ios_base& __base)
   {
@@ -580,6 +825,7 @@ namespace std
     return __base;
   }
 
+  /// Calls base.setf(ios_base::scientific, ios_base::floatfield).
   inline ios_base& 
   scientific(ios_base& __base)
   {
diff --git a/libstdc++-v3/include/bits/stl_deque.h b/libstdc++-v3/include/bits/stl_deque.h
index 7dbbbea7e83..454fed31bf7 100644
--- a/libstdc++-v3/include/bits/stl_deque.h
+++ b/libstdc++-v3/include/bits/stl_deque.h
@@ -1280,7 +1280,8 @@ namespace std
       }
   
     // called by the second initialize_dispatch above
-    /** @{
+    //@{
+    /**
      *  @if maint
      *  @brief Fills the deque with whatever is in [first,last).
      *  @param  first  An input iterator.
@@ -1302,7 +1303,7 @@ namespace std
       void
       _M_range_initialize(_ForwardIterator __first, _ForwardIterator __last,
                           forward_iterator_tag);
-    /** @} */
+    //@}
   
     /**
      *  @if maint
@@ -1383,7 +1384,8 @@ namespace std
     }
   
   
-    /** @{
+    //@{
+    /**
      *  @if maint
      *  @brief Helper functions for push_* and pop_*.
      *  @endif
@@ -1396,7 +1398,7 @@ namespace std
   #endif
     void _M_pop_back_aux();
     void _M_pop_front_aux();
-    /** @} */
+    //@}
   
   
     // Internal insert functions follow.  The *_aux functions do the actual
@@ -1462,7 +1464,8 @@ namespace std
     iterator _M_insert_aux(iterator __pos);
   #endif
   
-    /** @{
+    //@{
+    /**
      *  @if maint
      *  @brief Memory-handling helpers for the previous internal insert
      *         functions.
@@ -1491,10 +1494,11 @@ namespace std
   
     void
     _M_new_elements_at_back(size_type __new_elements);
-    /** @} */
+    //@}
   
   
-    /** @{
+    //@{
+    /**
      *  @if maint
      *  @brief Memory-handling helpers for the major %map.
      *
@@ -1519,7 +1523,7 @@ namespace std
   
     void
     _M_reallocate_map(size_type __nodes_to_add, bool __add_at_front);
-    /** @} */
+    //@}
   };
   
   
diff --git a/libstdc++-v3/include/bits/stl_iterator_base_types.h b/libstdc++-v3/include/bits/stl_iterator_base_types.h
index e7f131280c3..8b040e49602 100644
--- a/libstdc++-v3/include/bits/stl_iterator_base_types.h
+++ b/libstdc++-v3/include/bits/stl_iterator_base_types.h
@@ -68,7 +68,8 @@
 
 namespace std
 {
-  /** @{
+  //@{
+  /**
    *  @defgroup iterator_tags Iterator Tags
    *  These are empty types, used to distinguish different iterators.  The
    *  distinction is not made by what they contain, but simply by what they
diff --git a/libstdc++-v3/include/std/std_fstream.h b/libstdc++-v3/include/std/std_fstream.h
index c3861051d40..685a38dd944 100644
--- a/libstdc++-v3/include/std/std_fstream.h
+++ b/libstdc++-v3/include/std/std_fstream.h
@@ -50,6 +50,15 @@
 
 namespace std
 {
+  // [27.8.1.1] template class basic_filebuf
+  /**
+   *  @brief  The actual work of input and output (for files).
+   *
+   *  This class associates both its input and output sequence with an
+   *  external disk file, and maintains a joint file position for both
+   *  sequences.  Many of its sematics are described in terms of similar
+   *  behavior in the Standard C Library's @c FILE streams.
+  */
   template<typename _CharT, typename _Traits>
     class basic_filebuf : public basic_streambuf<_CharT, _Traits>
     {
@@ -61,7 +70,12 @@ namespace std
       typedef typename traits_type::pos_type 		pos_type;
       typedef typename traits_type::off_type 		off_type;
 
-      // Non-standard Types:
+      //@{
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       typedef basic_streambuf<char_type, traits_type>  	__streambuf_type;
       typedef basic_filebuf<char_type, traits_type>     __filebuf_type;
       typedef __basic_file<char>		        __file_type;
@@ -69,22 +83,43 @@ namespace std
       typedef codecvt<char_type, char, __state_type>    __codecvt_type;
       typedef typename __codecvt_type::result 	        __res_type;
       typedef ctype<char_type>                          __ctype_type;
+      //@}
 
       friend class ios_base; // For sync_with_stdio.
 
     protected:
       // Data Members:
       // MT lock inherited from libio or other low-level io library.
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       __c_lock          	_M_lock;
 
       // External buffer.
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       __file_type 		_M_file;
 
       // Current and beginning state type for codecvt.
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       __state_type		_M_state_cur;
       __state_type 		_M_state_beg;
 
       // Set iff _M_buf is allocated memory from _M_allocate_internal_buffer.
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       bool			_M_buf_allocated;
       
       // XXX Needed?
@@ -92,12 +127,26 @@ namespace std
 
       // The position in the buffer corresponding to the external file
       // pointer.
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       char_type*		_M_filepos;
 
     public:
       // Constructors/destructor:
+      /**
+       *  @brief  Does not open any files.
+       *
+       *  The default constructor initializes the parent class using its
+       *  own default ctor.
+      */
       basic_filebuf();
 
+      /**
+       *  @brief  The destructor closes the file first.
+      */
       virtual
       ~basic_filebuf()
       {
@@ -106,23 +155,61 @@ namespace std
       }
 
       // Members:
+      /**
+       *  @brief  Returns true if the external file is open.
+      */
       bool
       is_open() const { return _M_file.is_open(); }
 
+      /**
+       *  @brief  Opens an external file.
+       *  @param  s  The name of the file.
+       *  @param  mode  The open mode flags.
+       *  @return  @c this on success, NULL on failure
+       *
+       *  If a file is already open, this function immediately fails.
+       *  Otherwise it tries to open the file named @a s using the flags
+       *  given in @a mode.
+       *
+       *  [Table 92 gives the relation between openmode combinations and the
+       *  equivalent fopen() flags, but the table has not been copied yet.]
+      */
       __filebuf_type*
       open(const char* __s, ios_base::openmode __mode);
 
+      /**
+       *  @brief  Closes the currently associated file.
+       *  @return  @c this on success, NULL on failure
+       *
+       *  If no file is currently open, this function immediately fails.
+       *
+       *  If a "put buffer area" exists, @c overflow(eof) is called to flush
+       *  all the characters.  The file is then closed.
+       *
+       *  If any operations fail, this function also fails.
+      */
       __filebuf_type*
       close();
 
     protected:
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       void
       _M_allocate_internal_buffer();
 
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       void
       _M_destroy_internal_buffer();
 
-      // Overridden virtual functions:
+      // [27.8.1.4] overridden virtual functions
+      // [documentation is inherited]
       virtual streamsize
       showmanyc();
 
@@ -137,15 +224,23 @@ namespace std
       // the underflow() case in order to maintain synchronization.  So
       // instead of calling underflow() from uflow(), we create a common
       // subroutine to do the real work.
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       int_type
       _M_underflow_common(bool __bump);
 
+      // [documentation is inherited]
       virtual int_type
       underflow() { return _M_underflow_common(false); }
 
+      // [documentation is inherited]
       virtual int_type
       uflow() { return _M_underflow_common(true); }
 
+      // [documentation is inherited]
       virtual int_type
       pbackfail(int_type __c = _Traits::eof());
 
@@ -157,6 +252,8 @@ namespace std
       // this in actuality be a helper function that checks for the
       // eccentricities of this implementation, and then call
       // overflow() if indeed the buffer is full.
+
+      // [documentation is inherited]
       virtual int_type
       overflow(int_type __c = _Traits::eof());
 
@@ -167,25 +264,50 @@ namespace std
       // character c.
       // 27.5.2.4.5
       // Consume some sequence of the characters in the pending sequence.
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       int_type
       _M_really_overflow(int_type __c = _Traits::eof());
 
       // Convert internal byte sequence to external, char-based
       // sequence via codecvt.
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       void
       _M_convert_to_external(char_type*, streamsize, streamsize&, streamsize&);
 
+      /**
+       *  @brief  Manipulates the buffer.
+       *  @param  s  Pointer to a buffer area.
+       *  @param  n  Size of @a s.
+       *  @return  @c this
+       *
+       *  If no file has been opened, and both @a s and @a n are zero, then
+       *  the stream becomes unbuffered.  Otherwise, @c s is used as a
+       *  buffer; see
+       *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2
+       *  for more.
+      */
       virtual __streambuf_type*
       setbuf(char_type* __s, streamsize __n);
 
+      // [documentation is inherited]
       virtual pos_type
       seekoff(off_type __off, ios_base::seekdir __way,
 	      ios_base::openmode __mode = ios_base::in | ios_base::out);
 
+      // [documentation is inherited]
       virtual pos_type
       seekpos(pos_type __pos,
 	      ios_base::openmode __mode = ios_base::in | ios_base::out);
 
+      // [documentation is inherited]
       virtual int
       sync()
       {
@@ -207,9 +329,11 @@ namespace std
 	return 0;
       }
 
+      // [documentation is inherited]
       virtual void
       imbue(const locale& __loc);
 
+      // [documentation is inherited]
       virtual streamsize
       xsgetn(char_type* __s, streamsize __n)
       {
@@ -231,6 +355,7 @@ namespace std
 	return __ret;
       }
 
+      // [documentation is inherited]
       virtual streamsize
       xsputn(const char_type* __s, streamsize __n)
       {
@@ -238,6 +363,11 @@ namespace std
 	return __streambuf_type::xsputn(__s, __n);
       }
 
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       void
       _M_output_unshift();
 
@@ -248,6 +378,11 @@ namespace std
       // internal buffer does not truly reflect the contents of the
       // external buffer. At this point, for whatever reason, it is in
       // an indeterminate state.
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       void
       _M_set_indeterminate(void)
       {
@@ -258,6 +393,11 @@ namespace std
 	_M_filepos = _M_buf;
       }
 
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       void
       _M_set_determinate(off_type __off)
       {
@@ -270,6 +410,11 @@ namespace std
 	_M_filepos = _M_buf + __off;
       }
 
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       bool
       _M_is_indeterminate(void)
       { 
@@ -286,7 +431,7 @@ namespace std
       }
     };
 
-  // Explicit specializations.
+  // Explicit specializations, defined in src/fstream.cc.
   template<> 
     basic_filebuf<char>::int_type 
     basic_filebuf<char>::_M_underflow_common(bool __bump);
@@ -297,9 +442,14 @@ namespace std
     basic_filebuf<wchar_t>::_M_underflow_common(bool __bump);
  #endif
 
-  // 27.8.1.5  Template class basic_ifstream
+  // [27.8.1.5] Template class basic_ifstream
   /**
-   *  Derivation of general input streams, specific to files.
+   *  @brief  Controlling input for files.
+   *
+   *  This class supports reading from named files, using the inherited
+   *  functions from std::basic_istream.  To control the associated
+   *  sequence, an instance of std::basic_filebuf is used, which this page
+   *  refers to as @c sb.
   */
   template<typename _CharT, typename _Traits>
     class basic_ifstream : public basic_istream<_CharT, _Traits>
@@ -317,20 +467,33 @@ namespace std
       typedef basic_istream<char_type, traits_type>	__istream_type;
 
     private:
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       __filebuf_type	_M_filebuf;
 
     public:
-     // Constructors/Destructors:
-     /** Default constructor.  Create an input file stream.  */
+      // Constructors/Destructors:
+      /**
+       *  @brief  Default constructor.
+       *
+       *  Initializes @c sb using its default constructor, and passes
+       *  @c &sb to the base class initializer.  Does not open any files
+       *  (you haven't given it a filename to open).
+      */
       basic_ifstream()
       : __istream_type(NULL), _M_filebuf()
       { this->init(&_M_filebuf); }
 
       /**
-       *  @brief Create an input file stream.
-       *  @param  s  Null terminated string specifying filename.
+       *  @brief  Create an input file stream.
+       *  @param  s  Null terminated string specifying the filename.
        *  @param  mode  Open file in specified mode (see std::ios_base).
        *
+       *  @c ios_base::in is automatically included in @a mode.
+       *
        *  Tip:  When using std::string to hold the filename, you must use
        *  .c_str() before passing it to this constructor.
       */
@@ -342,21 +505,44 @@ namespace std
 	this->open(__s, __mode);
       }
 
+      /**
+       *  @brief  The destructor does nothing.
+       *
+       *  The file is closed by the filebuf object, not the formatting
+       *  stream.
+      */
       ~basic_ifstream()
       { }
 
       // Members:
       /**
-       *  @brief  Get a pointer to the file stream's buffer.
-       *  @return Pointer to basic_filebuf.
+       *  @brief  Accessing the underlying buffer.
+       *  @return  The current basic_filebuf buffer.
+       *
+       *  This hides both signatures of std::basic_ios::rdbuf().
       */
       __filebuf_type*
       rdbuf() const
       { return const_cast<__filebuf_type*>(&_M_filebuf); }
 
+      /**
+       *  @brief  Wrapper to test for an open file.
+       *  @return  @c rdbuf()->is_open()
+      */
       bool
       is_open() { return _M_filebuf.is_open(); }
 
+      /**
+       *  @brief  Opens an external file.
+       *  @param  s  The name of the file.
+       *  @param  mode  The open mode flags.
+       *
+       *  Calls @c std::basic_filebuf::open(s,mode|in).  If that function
+       *  fails, @c failbit is set in the stream's error state.
+       *
+       *  Tip:  When using std::string to hold the filename, you must use
+       *  .c_str() before passing it to this constructor.
+      */
       void
       open(const char* __s, ios_base::openmode __mode = ios_base::in)
       {
@@ -364,7 +550,12 @@ namespace std
 	  this->setstate(ios_base::failbit);
       }
 
-      /** Close the file.  */
+      /**
+       *  @brief  Close the file.
+       *
+       *  Calls @c std::basic_filebuf::close().  If that function
+       *  fails, @c failbit is set in the stream's error state.
+      */
       void
       close()
       {
@@ -374,9 +565,14 @@ namespace std
     };
 
 
-  // 27.8.1.8  Template class basic_ofstream
+  // [27.8.1.8] Template class basic_ofstream
   /**
-   *  Derivation of general output streams, specific to files.
+   *  @brief  Controlling output for files.
+   *
+   *  This class supports reading from named files, using the inherited
+   *  functions from std::basic_ostream.  To control the associated
+   *  sequence, an instance of std::basic_filebuf is used, which this page
+   *  refers to as @c sb.
   */
   template<typename _CharT, typename _Traits>
     class basic_ofstream : public basic_ostream<_CharT,_Traits>
@@ -394,20 +590,34 @@ namespace std
       typedef basic_ostream<char_type, traits_type>	__ostream_type;
 
     private:
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       __filebuf_type	_M_filebuf;
 
     public:
       // Constructors:
-      /** Default constructor for output file_stream.  */
+      /**
+       *  @brief  Default constructor.
+       *
+       *  Initializes @c sb using its default constructor, and passes
+       *  @c &sb to the base class initializer.  Does not open any files
+       *  (you haven't given it a filename to open).
+      */
       basic_ofstream()
       : __ostream_type(NULL), _M_filebuf()
       { this->init(&_M_filebuf); }
 
       /**
-       *  @brief  Create an output stream.
-       *  @param  s  Null terminated string specifying filename.
+       *  @brief  Create an output file stream.
+       *  @param  s  Null terminated string specifying the filename.
        *  @param  mode  Open file in specified mode (see std::ios_base).
        *
+       *  @c ios_base::out|ios_base::trunc is automatically included in
+       *  @a mode.
+       *
        *  Tip:  When using std::string to hold the filename, you must use
        *  .c_str() before passing it to this constructor.
       */
@@ -420,29 +630,40 @@ namespace std
 	this->open(__s, __mode);
       }
 
+      /**
+       *  @brief  The destructor does nothing.
+       *
+       *  The file is closed by the filebuf object, not the formatting
+       *  stream.
+      */
       ~basic_ofstream()
       { }
 
       // Members:
       /**
-       *  @brief  Get a pointer to the file stream's buffer.
-       *  @return Pointer to basic_filebuf.
+       *  @brief  Accessing the underlying buffer.
+       *  @return  The current basic_filebuf buffer.
+       *
+       *  This hides both signatures of std::basic_ios::rdbuf().
       */
       __filebuf_type*
       rdbuf() const
       { return const_cast<__filebuf_type*>(&_M_filebuf); }
 
       /**
-       *  @brief Query to see if file stream is open.
-       *  @return True if stream is open.
+       *  @brief  Wrapper to test for an open file.
+       *  @return  @c rdbuf()->is_open()
       */
       bool
       is_open() { return _M_filebuf.is_open(); }
 
       /**
-       *  @brief Specify a file to open for output.
-       *  @param  s  Null terminated string specifying filename.
-       *  @param  mode  Mode in which to open file (see std::ios_base).
+       *  @brief  Opens an external file.
+       *  @param  s  The name of the file.
+       *  @param  mode  The open mode flags.
+       *
+       *  Calls @c std::basic_filebuf::open(s,mode|out|trunc).  If that
+       *  function fails, @c failbit is set in the stream's error state.
        *
        *  Tip:  When using std::string to hold the filename, you must use
        *  .c_str() before passing it to this constructor.
@@ -455,7 +676,12 @@ namespace std
 	  this->setstate(ios_base::failbit);
       }
 
-      /** Close the file stream.  */
+      /**
+       *  @brief  Close the file.
+       *
+       *  Calls @c std::basic_filebuf::close().  If that function
+       *  fails, @c failbit is set in the stream's error state.
+      */
       void
       close()
       {
@@ -465,9 +691,14 @@ namespace std
     };
 
 
-  // 27.8.1.11  Template class basic_fstream
+  // [27.8.1.11] Template class basic_fstream
   /**
-   *  Derivation of general input/output streams, specific to files.
+   *  @brief  Controlling intput and output for files.
+   *
+   *  This class supports reading from and writing to named files, using
+   *  the inherited functions from std::basic_iostream.  To control the
+   *  associated sequence, an instance of std::basic_filebuf is used, which
+   *  this page refers to as @c sb.
   */
   template<typename _CharT, typename _Traits>
     class basic_fstream : public basic_iostream<_CharT, _Traits>
@@ -486,18 +717,29 @@ namespace std
       typedef basic_iostream<char_type, traits_type>	__iostream_type;
 
     private:
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       __filebuf_type	_M_filebuf;
 
     public:
       // Constructors/destructor:
-      /** Default constructor.  Create a file stream.  */
+      /**
+       *  @brief  Default constructor.
+       *
+       *  Initializes @c sb using its default constructor, and passes
+       *  @c &sb to the base class initializer.  Does not open any files
+       *  (you haven't given it a filename to open).
+      */
       basic_fstream()
       : __iostream_type(NULL), _M_filebuf()
       { this->init(&_M_filebuf); }
 
       /**
-       *  @brief Create an input/output stream.
-       *  @param  s  Null terminated string specifying filename.
+       *  @brief  Create an input/output file stream.
+       *  @param  s  Null terminated string specifying the filename.
        *  @param  mode  Open file in specified mode (see std::ios_base).
        *
        *  Tip:  When using std::string to hold the filename, you must use
@@ -512,29 +754,40 @@ namespace std
 	this->open(__s, __mode);
       }
 
+      /**
+       *  @brief  The destructor does nothing.
+       *
+       *  The file is closed by the filebuf object, not the formatting
+       *  stream.
+      */
       ~basic_fstream()
       { }
 
       // Members:
       /**
-       *  @brief  Get a pointer to the file stream's buffer.
-       *  @return Pointer to basic_filebuf.
+       *  @brief  Accessing the underlying buffer.
+       *  @return  The current basic_filebuf buffer.
+       *
+       *  This hides both signatures of std::basic_ios::rdbuf().
       */
       __filebuf_type*
       rdbuf() const
       { return const_cast<__filebuf_type*>(&_M_filebuf); }
 
       /**
-       *  @brief Query to see if file stream is open.
-       *  @return True if stream is open.
+       *  @brief  Wrapper to test for an open file.
+       *  @return  @c rdbuf()->is_open()
       */
       bool
       is_open() { return _M_filebuf.is_open(); }
 
       /**
-       *  @brief Specify a file to open for input and/or output.
-       *  @param  s  Null terminated string specifying filename.
-       *  @param  mode  Mode in which to open file (see std::ios_base).
+       *  @brief  Opens an external file.
+       *  @param  s  The name of the file.
+       *  @param  mode  The open mode flags.
+       *
+       *  Calls @c std::basic_filebuf::open(s,mode).  If that
+       *  function fails, @c failbit is set in the stream's error state.
        *
        *  Tip:  When using std::string to hold the filename, you must use
        *  .c_str() before passing it to this constructor.
@@ -547,7 +800,12 @@ namespace std
 	  setstate(ios_base::failbit);
       }
 
-      /** Close the file stream.  */
+      /**
+       *  @brief  Close the file.
+       *
+       *  Calls @c std::basic_filebuf::close().  If that function
+       *  fails, @c failbit is set in the stream's error state.
+      */
       void
       close()
       {
diff --git a/libstdc++-v3/include/std/std_iomanip.h b/libstdc++-v3/include/std/std_iomanip.h
index 23237ce210d..26756a8041c 100644
--- a/libstdc++-v3/include/std/std_iomanip.h
+++ b/libstdc++-v3/include/std/std_iomanip.h
@@ -47,8 +47,18 @@
 
 namespace std
 {
+  // [27.6.3] standard manipulators
+  // Also see DR 183.
+
   struct _Resetiosflags { ios_base::fmtflags _M_mask; };
 
+  /**
+   *  @brief  Manipulator for @c setf.
+   *  @param  mask  A format flags mask.
+   *
+   *  Sent to a stream object, this manipulator resets the specified flags,
+   *  via @e stream.setf(0,mask).
+  */
   inline _Resetiosflags 
   resetiosflags(ios_base::fmtflags __mask)
   { 
@@ -76,6 +86,13 @@ namespace std
 
   struct _Setiosflags { ios_base::fmtflags _M_mask; };
 
+  /**
+   *  @brief  Manipulator for @c setf.
+   *  @param  mask  A format flags mask.
+   *
+   *  Sent to a stream object, this manipulator sets the format flags
+   *  to @a mask.
+  */
   inline _Setiosflags 
   setiosflags(ios_base::fmtflags __mask)
   { 
@@ -103,6 +120,14 @@ namespace std
 
   struct _Setbase { int _M_base; };
 
+  /**
+   *  @brief  Manipulator for @c setf.
+   *  @param  base  A numeric base.
+   *
+   *  Sent to a stream object, this manipulator changes the
+   *  @c ios_base::basefield flags to @c oct, @c dec, or @c hex when @a base
+   *  is 8, 10, or 16, accordingly, and to 0 if @a base is any other value.
+  */
   inline _Setbase 
   setbase(int __base)
   { 
@@ -137,6 +162,13 @@ namespace std
   template<typename _CharT> 
     struct _Setfill { _CharT _M_c; };
 
+  /**
+   *  @brief  Manipulator for @c fill.
+   *  @param  c  The new fill character.
+   *
+   *  Sent to a stream object, this manipulator calls @c fill(c) for that
+   *  object.
+  */
   template<typename _CharT> 
     inline _Setfill<_CharT> 
     setfill(_CharT __c)
@@ -165,6 +197,13 @@ namespace std
 
   struct _Setprecision { int _M_n; };
 
+  /**
+   *  @brief  Manipulator for @c precision.
+   *  @param  n  The new precision.
+   *
+   *  Sent to a stream object, this manipulator calls @c precision(n) for
+   *  that object.
+  */
   inline _Setprecision 
   setprecision(int __n)
   { 
@@ -192,6 +231,13 @@ namespace std
 
   struct _Setw { int _M_n; };
 
+  /**
+   *  @brief  Manipulator for @c width.
+   *  @param  n  The new width.
+   *
+   *  Sent to a stream object, this manipulator calls @c width(n) for
+   *  that object.
+  */
   inline _Setw 
   setw(int __n)
   { 
diff --git a/libstdc++-v3/include/std/std_iosfwd.h b/libstdc++-v3/include/std/std_iosfwd.h
index 797f4936dc8..124c8ffc5ff 100644
--- a/libstdc++-v3/include/std/std_iosfwd.h
+++ b/libstdc++-v3/include/std/std_iosfwd.h
@@ -102,35 +102,64 @@ namespace std
   class ios_base; 
 #endif
 
-  typedef basic_ios<char> 		ios;
-  typedef basic_streambuf<char> 	streambuf;
-  typedef basic_istream<char> 		istream;
-  typedef basic_ostream<char> 		ostream;
-  typedef basic_iostream<char> 		iostream;
-  typedef basic_stringbuf<char> 	stringbuf;
-  typedef basic_istringstream<char> 	istringstream;
-  typedef basic_ostringstream<char> 	ostringstream;
-  typedef basic_stringstream<char> 	stringstream;
-  typedef basic_filebuf<char> 		filebuf;
-  typedef basic_ifstream<char> 		ifstream;
-  typedef basic_ofstream<char> 		ofstream;
-  typedef basic_fstream<char> 		fstream;
+  /** 
+   *  @defgroup s27_2_iosfwd I/O Forward Declarations
+   *
+   *  Nearly all of the I/O classes are parameterized on the type of
+   *  characters they read and write.  (The major exception is ios_base at
+   *  the top of the hierarchy.)  This is a change from pre-Standard
+   *  streams, which were not templates.
+   *
+   *  For ease of use and compatibility, all of the basic_* I/O-related
+   *  classes are given typedef names for both of the builtin character
+   *  widths (wide and narrow).  The typedefs are the same as the
+   *  pre-Standard names, for example:
+   *
+   *  @code
+   *     typedef basic_ifstream<char>  ifstream;
+   *  @endcode
+   *
+   *  Because properly forward-declaring these classes can be difficult, you
+   *  should not do it yourself.  Instead, include the &lt;iosfwd&gt;
+   *  header, which contains only declarations of all the I/O classes as
+   *  well as the typedefs.  Trying to forward-declare the typedefs
+   *  themselves (e.g., "class ostream;") is not valid ISO C++.
+   *
+   *  For more specific declarations, see
+   *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#10
+   *
+   *  @{
+  */
+  typedef basic_ios<char> 		ios;		///< @isiosfwd
+  typedef basic_streambuf<char> 	streambuf;	///< @isiosfwd
+  typedef basic_istream<char> 		istream;	///< @isiosfwd
+  typedef basic_ostream<char> 		ostream;	///< @isiosfwd
+  typedef basic_iostream<char> 		iostream;	///< @isiosfwd
+  typedef basic_stringbuf<char> 	stringbuf;	///< @isiosfwd
+  typedef basic_istringstream<char> 	istringstream;	///< @isiosfwd
+  typedef basic_ostringstream<char> 	ostringstream;	///< @isiosfwd
+  typedef basic_stringstream<char> 	stringstream;	///< @isiosfwd
+  typedef basic_filebuf<char> 		filebuf;	///< @isiosfwd
+  typedef basic_ifstream<char> 		ifstream;	///< @isiosfwd
+  typedef basic_ofstream<char> 		ofstream;	///< @isiosfwd
+  typedef basic_fstream<char> 		fstream;	///< @isiosfwd
 
 #ifdef _GLIBCPP_USE_WCHAR_T
-  typedef basic_ios<wchar_t> 		wios;
-  typedef basic_streambuf<wchar_t> 	wstreambuf;
-  typedef basic_istream<wchar_t> 	wistream;
-  typedef basic_ostream<wchar_t> 	wostream;
-  typedef basic_iostream<wchar_t> 	wiostream;
-  typedef basic_stringbuf<wchar_t> 	wstringbuf;
-  typedef basic_istringstream<wchar_t> 	wistringstream;
-  typedef basic_ostringstream<wchar_t> 	wostringstream;
-  typedef basic_stringstream<wchar_t> 	wstringstream;
-  typedef basic_filebuf<wchar_t> 	wfilebuf;
-  typedef basic_ifstream<wchar_t> 	wifstream;
-  typedef basic_ofstream<wchar_t> 	wofstream;
-  typedef basic_fstream<wchar_t> 	wfstream;
+  typedef basic_ios<wchar_t> 		wios;		///< @isiosfwd
+  typedef basic_streambuf<wchar_t> 	wstreambuf;	///< @isiosfwd
+  typedef basic_istream<wchar_t> 	wistream;	///< @isiosfwd
+  typedef basic_ostream<wchar_t> 	wostream;	///< @isiosfwd
+  typedef basic_iostream<wchar_t> 	wiostream;	///< @isiosfwd
+  typedef basic_stringbuf<wchar_t> 	wstringbuf;	///< @isiosfwd
+  typedef basic_istringstream<wchar_t> 	wistringstream;	///< @isiosfwd
+  typedef basic_ostringstream<wchar_t> 	wostringstream;	///< @isiosfwd
+  typedef basic_stringstream<wchar_t> 	wstringstream;	///< @isiosfwd
+  typedef basic_filebuf<wchar_t> 	wfilebuf;	///< @isiosfwd
+  typedef basic_ifstream<wchar_t> 	wifstream;	///< @isiosfwd
+  typedef basic_ofstream<wchar_t> 	wofstream;	///< @isiosfwd
+  typedef basic_fstream<wchar_t> 	wfstream;	///< @isiosfwd
 #endif
+  /** @}  */
 } // namespace std
 
 #endif
diff --git a/libstdc++-v3/include/std/std_iostream.h b/libstdc++-v3/include/std/std_iostream.h
index d0736b83513..d70949377df 100644
--- a/libstdc++-v3/include/std/std_iostream.h
+++ b/libstdc++-v3/include/std/std_iostream.h
@@ -47,17 +47,31 @@
 
 namespace std 
 {
-  extern istream cin;
-  extern ostream cout;
-  extern ostream cerr;
-  extern ostream clog;
+  /**
+   *  @name Standard Stream Objects
+   *
+   *  The &lt;iostream&gt; header declares the eight <em>standard stream
+   *  objects</em>.  For other declarations, see
+   *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#10 and the
+   *  @link s27_2_iosfwd I/O forward declarations @endlink
+   *
+   *  They are required by default to cooperate with the global C library's
+   *  @c FILE streams, and to be available during program startup and
+   *  termination.  For more information, see the HOWTO linked to above.
+  */
+  //@{
+  extern istream cin;		///< Linked to standard input
+  extern ostream cout;		///< Linked to standard output
+  extern ostream cerr;		///< Linked to standard error (unbuffered)
+  extern ostream clog;		///< Linked to standard error (buffered)
 
 #ifdef _GLIBCPP_USE_WCHAR_T
-  extern wistream wcin;
-  extern wostream wcout;
-  extern wostream wcerr;
-  extern wostream wclog;
+  extern wistream wcin;		///< Linked to standard input
+  extern wostream wcout;	///< Linked to standard output
+  extern wostream wcerr;	///< Linked to standard error (unbuffered)
+  extern wostream wclog;	///< Linked to standard error (buffered)
 #endif
+  //@}
 
   // For construction of filebuffers for cout, cin, cerr, clog et. al.
   static ios_base::Init __ioinit;
diff --git a/libstdc++-v3/include/std/std_istream.h b/libstdc++-v3/include/std/std_istream.h
index 8aa9123ed5c..7e050322328 100644
--- a/libstdc++-v3/include/std/std_istream.h
+++ b/libstdc++-v3/include/std/std_istream.h
@@ -46,7 +46,14 @@
 
 namespace std
 {
-  // 27.6.1.1 Template class basic_istream
+  // [27.6.1.1] Template class basic_istream
+  /**
+   *  @brief  Controlling input.
+   *
+   *  This is the base class for all input streams.  It provides text
+   *  formatting of all builtin types, and communicates with any class
+   *  derived from basic_streambuf to do the actual input.
+  */
   template<typename _CharT, typename _Traits>
     class basic_istream : virtual public basic_ios<_CharT, _Traits>
     {
@@ -68,10 +75,23 @@ namespace std
 
     protected:
       // Data Members:
+      /**
+       *  @if maint
+       *  The number of characters extracted in the previous unformatted
+       *  function; see gcount().
+       *  @endif
+      */
       streamsize 		_M_gcount;
 
     public:
-      // 27.6.1.1.1 Constructor/destructor:
+      // [27.6.1.1.1] constructor/destructor
+      /**
+       *  @brief  Base constructor.
+       *
+       *  This ctor is almost never called by the user directly, rather from
+       *  derived classes' initialization lists, which pass a pointer to
+       *  their own stream buffer.
+      */
       explicit 
       basic_istream(__streambuf_type* __sb)
       { 
@@ -79,16 +99,29 @@ namespace std
 	_M_gcount = streamsize(0);
       }
 
+      /**
+       *  @brief  Base destructor.
+       *
+       *  This does very little apart from providing a virtual base dtor.
+      */
       virtual 
       ~basic_istream() 
       { _M_gcount = streamsize(0); }
 
-      // 27.6.1.1.2 Prefix/suffix:
+      // [27.6.1.1.2] prefix/suffix
       class sentry;
       friend class sentry;
 
-      // 27.6.1.2 Formatted input:
-      // 27.6.1.2.3 basic_istream::operator>>
+      // [27.6.1.2] formatted input
+      // [27.6.1.2.3] basic_istream::operator>>
+      //@{
+      /**
+       *  @brief  Interface for manipulators.
+       *
+       *  Manuipulators such as @c std::ws and @c std::dec use these
+       *  functions in constructs like "std::cin >> std::ws".  For more
+       *  information, see the iomanip header.
+      */
       __istream_type&
       operator>>(__istream_type& (*__pf)(__istream_type&));
 
@@ -97,8 +130,36 @@ namespace std
 
       __istream_type&
       operator>>(ios_base& (*__pf)(ios_base&));
+      //@}
       
-      // 27.6.1.2.2 Arithmetic Extractors
+      // [27.6.1.2.2] arithmetic extractors
+      /**
+       *  @name Arithmetic Extractors
+       *
+       *  All the @c operator>> functions (aka <em>formatted input
+       *  functions</em>) have some common behavior.  Each starts by
+       *  constructing a temporary object of type std::basic_istream::sentry
+       *  with the second argument (noskipws) set to false.  This has several
+       *  effects, concluding with the setting of a status flag; see the
+       *  sentry documentation for more.
+       *
+       *  If the sentry status is good, the function tries to extract
+       *  whatever data is appropriate for the type of the argument.
+       *
+       *  If an exception is thrown during extraction, ios_base::badbit
+       *  will be turned on in the stream's error state without causing an
+       *  ios_base::failure to be thrown.  The original exception will then
+       *  be rethrown.
+      */
+      //@{
+      /**
+       *  @brief  Basic arithmetic extractors
+       *  @param  A variable of builtin type.
+       *  @return  @c *this if successful
+       *
+       *  These functions use the stream's current locale (specifically, the
+       *  @c num_get facet) to parse the input data.
+      */
       __istream_type& 
       operator>>(bool& __n);
       
@@ -140,92 +201,444 @@ namespace std
       __istream_type& 
       operator>>(void*& __p);
 
+      /**
+       *  @brief  Extracting into another streambuf.
+       *  @param  sb  A pointer to a streambuf
+       *
+       *  This function behaves like one of the basic arithmetic extractors,
+       *  in that it also constructs a sentry onject and has the same error
+       *  handling behavior.
+       *
+       *  If @a sb is NULL, the stream will set failbit in its error state.
+       *
+       *  Characters are extracted from this stream and inserted into the
+       *  @a sb streambuf until one of the following occurs:
+       *
+       *  - the input stream reaches end-of-file,
+       *  - insertion into the output buffer fails (in this case, the
+       *    character that would have been inserted is not extracted), or
+       *  - an exception occurs (and in this case is caught)
+       *
+       *  If the function inserts no characters, failbit is set.
+      */
       __istream_type& 
       operator>>(__streambuf_type* __sb);
+      //@}
       
-      // 27.6.1.3 Unformatted input:
+      // [27.6.1.3] unformatted input
+      /**
+       *  @brief  Character counting
+       *  @return  The number of characters extracted by the previous
+       *           unformatted input function dispatched for this stream.
+      */
       inline streamsize 
-      gcount(void) const 
+      gcount() const 
       { return _M_gcount; }
       
+      /**
+       *  @name Unformatted Input Functions
+       *
+       *  All the unformatted input functions have some common behavior.
+       *  Each starts by constructing a temporary object of type
+       *  std::basic_istream::sentry with the second argument (noskipws)
+       *  set to true.  This has several effects, concluding with the
+       *  setting of a status flag; see the sentry documentation for more.
+       *
+       *  If the sentry status is good, the function tries to extract
+       *  whatever data is appropriate for the type of the argument.
+       *
+       *  The number of characters extracted is stored for later retrieval
+       *  by gcount().
+       *
+       *  If an exception is thrown during extraction, ios_base::badbit
+       *  will be turned on in the stream's error state without causing an
+       *  ios_base::failure to be thrown.  The original exception will then
+       *  be rethrown.
+      */
+      //@{
+      /**
+       *  @brief  Simple extraction.
+       *  @return  A character, or eof().
+       *
+       *  Tries to extract a character.  If none are available, sets failbit
+       *  and returns traits::eof().
+      */
       int_type 
-      get(void);
-
+      get();
+
+      /**
+       *  @brief  Simple extraction.
+       *  @param  c  The character in which to store data.
+       *  @return  *this
+       *
+       *  Tries to extract a character and store it in @a c.  If none are
+       *  available, sets failbit and returns traits::eof().
+       *
+       *  @note  This function is not overloaded on signed char and
+       *         unsigned char.
+      */
       __istream_type& 
       get(char_type& __c);
 
+      /**
+       *  @brief  Simple multiple-character extraction.
+       *  @param  s  Pointer to an array.
+       *  @param  n  Maximum number of characters to store in @a s.
+       *  @param  delim  A "stop" character.
+       *  @return  *this
+       *
+       *  Characters are extracted and stored into @a s until one of the
+       *  following happens:
+       *
+       *  - @c n-1 characters are stored
+       *  - the input sequence reaches EOF
+       *  - the next character equals @a delim, in which case the character
+       *    is not extracted
+       *
+       * If no characters are stored, failbit is set in the stream's error
+       * state.
+       *
+       * In any case, a null character is stored into the next location in
+       * the array.
+       *
+       *  @note  This function is not overloaded on signed char and
+       *         unsigned char.
+      */
       __istream_type& 
       get(char_type* __s, streamsize __n, char_type __delim);
 
+      /**
+       *  @brief  Simple multiple-character extraction.
+       *  @param  s  Pointer to an array.
+       *  @param  n  Maximum number of characters to store in @a s.
+       *  @return  *this
+       *
+       *  Returns @c get(s,n,widen('\n')).
+      */
       inline __istream_type& 
       get(char_type* __s, streamsize __n)
       { return this->get(__s, __n, this->widen('\n')); }
 
+      /**
+       *  @brief  Extraction into another streambuf.
+       *  @param  sb  A streambuf in which to store data.
+       *  @param  delim  A "stop" character.
+       *  @return  *this
+       *
+       *  Characters are extracted and inserted into @a sb until one of the
+       *  following happens:
+       *
+       *  - the input sequence reaches EOF
+       *  - insertion into the output buffer fails (in this case, the
+       *    character that would have been inserted is not extracted)
+       *  - the next character equals @a delim (in this case, the character
+       *    is not extracted)
+       *  - an exception occurs (and in this case is caught)
+       *
+       * If no characters are stored, failbit is set in the stream's error
+       * state.
+      */
       __istream_type&
       get(__streambuf_type& __sb, char_type __delim);
 
+      /**
+       *  @brief  Extraction into another streambuf.
+       *  @param  sb  A streambuf in which to store data.
+       *  @return  *this
+       *
+       *  Returns @c get(sb,widen('\n')).
+      */
       inline __istream_type&
       get(__streambuf_type& __sb)
       { return this->get(__sb, this->widen('\n')); }
 
+      /**
+       *  @brief  String extraction.
+       *  @param  s  A character array in which to store the data.
+       *  @param  n  Maximum number of characters to extract.
+       *  @param  delim  A "stop" character.
+       *  @return  *this
+       *
+       *  Extracts and stores characters into @a s until one of the
+       *  following happens.  Note that these criteria are required to be
+       *  tested in the order listed here, to allow an input line to exactly
+       *  fill the @a s array without setting failbit.
+       *
+       *  -# the input sequence reaches end-of-file, in which case eofbit
+       *     is set in the stream error state
+       *  -# the next character equals @c delim, in which case the character
+       *     is extracted (and therefore counted in @c gcount()) but not stored
+       *  -# @c n-1 characters are stored, in which case failbit is set
+       *     in the stream error state
+       *
+       *  If no characters are extracted, failbit is set.  (An empty line of
+       *  input should therefore not cause failbit to be set.)
+       *
+       *  In any case, a null character is stored in the next location in
+       *  the array.
+      */
       __istream_type& 
       getline(char_type* __s, streamsize __n, char_type __delim);
 
+      /**
+       *  @brief  String extraction.
+       *  @param  s  A character array in which to store the data.
+       *  @param  n  Maximum number of characters to extract.
+       *  @return  *this
+       *
+       *  Returns @c getline(s,n,widen('\n')).
+      */
       inline __istream_type& 
       getline(char_type* __s, streamsize __n)
       { return this->getline(__s, __n, this->widen('\n')); }
 
+      /**
+       *  @brief  Discarding characters
+       *  @param  n  Number of characters to discard.
+       *  @param  delim  A "stop" character.
+       *  @return  *this
+       *
+       *  Extracts characters and throws them away until one of the
+       *  following happens:
+       *  - if @a n @c != @c std::numeric_limits<int>::max(), @a n
+       *    characters are extracted
+       *  - the input sequence reaches end-of-file
+       *  - the next character equals @a delim (in this case, the character
+       *    is extracted); note that this condition will never occur if
+       *    @a delim equals @c traits::eof().
+      */
       __istream_type& 
       ignore(streamsize __n = 1, int_type __delim = traits_type::eof());
       
+      /**
+       *  @brief  Looking ahead in the stream
+       *  @return  The next character, or eof().
+       *
+       *  If, after constructing the sentry object, @c good() is false,
+       *  returns @c traits::eof().  Otherwise reads but does not extract
+       *  the next input character.
+      */
       int_type 
-      peek(void);
+      peek();
       
+      /**
+       *  @brief  Extraction without delimiters.
+       *  @param  s  A character array.
+       *  @param  n  Maximum number of characters to store.
+       *  @return  *this
+       *
+       *  If the stream state is @c good(), extracts characters and stores
+       *  them into @a s until one of the following happens:
+       *  - @a n characters are stored
+       *  - the input sequence reaches end-of-file, in which case the error
+       *    state is set to @c failbit|eofbit.
+       *
+       *  @note  This function is not overloaded on signed char and
+       *         unsigned char.
+      */
       __istream_type& 
       read(char_type* __s, streamsize __n);
 
+      /**
+       *  @brief  Extraction until the buffer is exhausted, but no more.
+       *  @param  s  A character array.
+       *  @param  n  Maximum number of characters to store.
+       *  @return  The number of characters extracted.
+       *
+       *  Extracts characters and stores them into @a s depending on the
+       *  number of characters remaining in the streambuf's buffer,
+       *  @c rdbuf()->in_avail(), called @c A here:
+       *  - if @c A @c == @c -1, sets eofbit and extracts no characters
+       *  - if @c A @c == @c 0, extracts no characters
+       *  - if @c A @c > @c 0, extracts @c min(A,n)
+       *
+       *  The goal is to empty the current buffer, and to not request any
+       *  more from the external input sequence controlled by the streambuf.
+      */
       streamsize 
       readsome(char_type* __s, streamsize __n);
       
+      /**
+       *  @brief  Unextracting a single character.
+       *  @param  c  The character to push back into the input stream.
+       *  @return  *this
+       *
+       *  If @c rdbuf() is not null, calls @c rdbuf()->sputbackc(c).
+       *
+       *  If @c rdbuf() is null or if @c sputbackc() fails, sets badbit in
+       *  the error state.
+       *
+       *  @note  Since no characters are extracted, the next call to
+       *         @c gcount() will return 0, as required by DR 60.
+       *
+       *  @if maint
+       *  FIXME We don't comply with DR 60 here, _M_gcount is untouched.
+       *  @endif
+      */
       __istream_type& 
       putback(char_type __c);
 
+      /**
+       *  @brief  Unextracting the previous character.
+       *  @return  *this
+       *
+       *  If @c rdbuf() is not null, calls @c rdbuf()->sungetc(c).
+       *
+       *  If @c rdbuf() is null or if @c sungetc() fails, sets badbit in
+       *  the error state.
+       *
+       *  @note  Since no characters are extracted, the next call to
+       *         @c gcount() will return 0, as required by DR 60.
+      */
       __istream_type& 
-      unget(void);
-
+      unget();
+
+      /**
+       *  @brief  Synchronizing the stream buffer.
+       *  @return  0 on success, -1 on failure
+       *
+       *  If @c rdbuf() is a null pointer, returns -1.
+       *
+       *  Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1,
+       *  sets badbit and returns -1.
+       *
+       *  Otherwise, returns 0.
+       *
+       *  @note  This function does not count the number of characters
+       *         extracted, if any, and therefore does not affect the next
+       *         call to @c gcount().
+       *  @if maint
+       *  FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
+       *  @endif
+      */
       int 
-      sync(void);
-
+      sync();
+
+      /**
+       *  @brief  Getting the current read position.
+       *  @return  A file position object.
+       *
+       *  If @c fail() is not false, returns @c pos_type(-1) to indicate
+       *  failure.  Otherwise returns @c rdbuf()->pubseekoff(0,cur,in).
+       *
+       *  @note  This function does not count the number of characters
+       *         extracted, if any, and therefore does not affect the next
+       *         call to @c gcount().
+      */
       pos_type 
-      tellg(void);
-
+      tellg();
+
+      /**
+       *  @brief  Changing the current read position.
+       *  @param  pos  A file position object.
+       *  @return  *this
+       *
+       *  If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos).  If
+       *  that function fails, sets failbit.
+       *
+       *  @note  This function does not count the number of characters
+       *         extracted, if any, and therefore does not affect the next
+       *         call to @c gcount().
+       *  @if maint
+       *  FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
+       *  @endif
+      */
       __istream_type& 
       seekg(pos_type);
 
+      /**
+       *  @brief  Changing the current read position.
+       *  @param  off  A file offset object.
+       *  @param  dir  The direction in which to seek.
+       *  @return  *this
+       *
+       *  If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir).
+       *  If that function fails, sets failbit.
+       *
+       *  @note  This function does not count the number of characters
+       *         extracted, if any, and therefore does not affect the next
+       *         call to @c gcount().
+       *  @if maint
+       *  FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
+       *  @endif
+      */
       __istream_type& 
       seekg(off_type, ios_base::seekdir);
+      //@}
     };
   
+  /**
+   *  @brief  Performs setup work for input streams.
+   *
+   *  Objects of this class are created before all of the standard
+   *  extractors are run.  It is responsible for "exception-safe prefix and
+   *  suffix operations," although only prefix actions are currently required
+   *  by the standard.  Additional actions may be added by the
+   *  implementation, and we list them in
+   *  http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#5
+   *  under [27.6] notes.
+  */
   template<typename _CharT, typename _Traits>
     class basic_istream<_CharT, _Traits>::sentry
     {
     public:
+      /// Easy access to dependant types.
       typedef _Traits 					traits_type;
       typedef basic_streambuf<_CharT, _Traits> 		__streambuf_type;
       typedef basic_istream<_CharT, _Traits> 		__istream_type;
       typedef typename __istream_type::__ctype_type 	__ctype_type;
       typedef typename _Traits::int_type		__int_type;
 
+      /**
+       *  @brief  The constructor performs all the work.
+       *  @param  is  The input stream to guard.
+       *  @param  noskipws  Whether to consume whitespace or not.
+       *
+       *  If the stream state is good (@a is.good() is true), then the
+       *  following actions are performed, otherwise the sentry state is
+       *  false ("not okay") and failbit is set in the stream state.
+       *
+       *  The sentry's preparatory actions are:
+       *
+       *  -# if the stream is tied to an output stream, @c is.tie()->flush()
+       *     is called to synchronize the output sequence
+       *  -# if @a noskipws is false, and @c ios_base::skipws is set in
+       *     @c is.flags(), the sentry extracts and discards whitespace
+       *     characters from the stream.  The currently imbued locale is
+       *     used to determine whether each character is whitespace.
+       *
+       *  If the stream state is still good, then the sentry state becomes
+       *  true ("okay").
+      */
       explicit 
       sentry(basic_istream<_CharT, _Traits>& __is, bool __noskipws = false);
 
+      /**
+       *  @brief  Quick status checking.
+       *  @return  The sentry state.
+       *
+       *  For ease of use, sentries may be converted to booleans.  The
+       *  return value is that of the sentry state (true == okay).
+      */
       operator bool() { return _M_ok; }
 
     private:
       bool _M_ok;
     };
 
-  // 27.6.1.2.3 Character extraction templates
+  // [27.6.1.2.3] character extraction templates
+  //@{
+  /**
+   *  @brief  Character extractors
+   *  @param  in  An input stream.
+   *  @param  c  A character reference.
+   *  @return  in
+   *
+   *  Behaves like one of the formatted arithmetic extractors described in
+   *  std::basic_istream.  After constructing a sentry object with good
+   *  status, this function extracts a character (if one is available) and
+   *  stores it in @a c.  Otherwise, sets failbit in the input stream.
+  */
   template<typename _CharT, typename _Traits>
     basic_istream<_CharT, _Traits>&
     operator>>(basic_istream<_CharT, _Traits>& __in, _CharT& __c);
@@ -239,7 +652,34 @@ namespace std
     basic_istream<char, _Traits>&
     operator>>(basic_istream<char, _Traits>& __in, signed char& __c)
     { return (__in >> reinterpret_cast<char&>(__c)); }
-
+  //@}
+
+  //@{
+  /**
+   *  @brief  Character string extractors
+   *  @param  in  An input stream.
+   *  @param  s  A pointer to a character array.
+   *  @return  in
+   *
+   *  Behaves like one of the formatted arithmetic extractors described in
+   *  std::basic_istream.  After constructing a sentry object with good
+   *  status, this function extracts up to @c n characters and stores them
+   *  into the array starting at @a s.  @c n is defined as:
+   *
+   *  - if @c width() is greater than zero, @c n is width()
+   *  - otherwise @c n is "the number of elements of the largest array of
+   *    @c char_type that can store a terminating @c eos." [27.6.1.2.3]/6
+   *
+   *  Characters are extracted and stored until one of the following happens:
+   *  - @c n-1 characters are stored
+   *  - EOF is reached
+   *  - the next character is whitespace according to the current locale
+   *  - the next character is a null byte (i.e., @c charT() )
+   *
+   *  @c width(0) is then called for the input stream.
+   *
+   *  If no characters are extracted, sets failbit.
+  */
   template<typename _CharT, typename _Traits>
     basic_istream<_CharT, _Traits>&
     operator>>(basic_istream<_CharT, _Traits>& __in, _CharT* __s);
@@ -253,8 +693,15 @@ namespace std
     basic_istream<char,_Traits>&
     operator>>(basic_istream<char,_Traits>& __in, signed char* __s)
     { return (__in >> reinterpret_cast<char*>(__s)); }
+  //@}
 
   // 27.6.1.5 Template class basic_iostream
+  /**
+   *  @brief  Merging istream and ostream capabilities.
+   *
+   *  This class multiply inherits from the input and output stream classes
+   *  simply to provide a single interface.
+  */
   template<typename _CharT, typename _Traits>
     class basic_iostream
     : public basic_istream<_CharT, _Traits>, 
@@ -275,16 +722,45 @@ namespace std
       typedef basic_istream<_CharT, _Traits>		__istream_type;
       typedef basic_ostream<_CharT, _Traits>		__ostream_type;
 
+      /**
+       *  @brief  Constructor does nothing.
+       *
+       *  Both of the parent classes are initialized with the same
+       *  streambuf pointer passed to this constructor.
+      */
       explicit 
       basic_iostream(basic_streambuf<_CharT, _Traits>* __sb)
       : __istream_type(__sb), __ostream_type(__sb)
       { }
 
+      /**
+       *  @brief  Destructor does nothing.
+      */
       virtual 
       ~basic_iostream() { }
     };
 
-  // 27.6.1.4 Standard basic_istream manipulators
+  // [27.6.1.4] standard basic_istream manipulators
+  /**
+   *  @brief  Quick and easy way to eat whitespace
+   *
+   *  This manipulator extracts whitespace characters, stopping when the
+   *  next character is non-whitespace, or when the input sequence is empty.
+   *  If the sequence is empty, @c eofbit is set in the stream, but not
+   *  @c failbit.
+   *
+   *  The current locale is used to distinguish whitespace characters.
+   *
+   *  Example:
+   *  @code
+   *     MyClass   mc;
+   *
+   *     std::cin >> std::ws >> mc;
+   *  @endcode
+   *  will skip leading whitespace before calling operator>> on cin and your
+   *  object.  Note that the same effect can be achieved by creating a
+   *  std::basic_istream::sentry inside your definition of operator>>.
+  */
   template<typename _CharT, typename _Traits>
     basic_istream<_CharT, _Traits>& 
     ws(basic_istream<_CharT, _Traits>& __is);
diff --git a/libstdc++-v3/include/std/std_ostream.h b/libstdc++-v3/include/std/std_ostream.h
index eff4bb5119f..7a553296102 100644
--- a/libstdc++-v3/include/std/std_ostream.h
+++ b/libstdc++-v3/include/std/std_ostream.h
@@ -46,7 +46,14 @@
 
 namespace std
 {
-  // 27.6.2.1 Template class basic_ostream
+  // [27.6.2.1] Template class basic_ostream
+  /**
+   *  @brief  Controlling output.
+   *
+   *  This is the base class for all output streams.  It provides text
+   *  formatting of all builtin types, and communicates with any class
+   *  derived from basic_streambuf to do the actual output.
+  */
   template<typename _CharT, typename _Traits>
     class basic_ostream : virtual public basic_ios<_CharT, _Traits>
     {
@@ -66,20 +73,40 @@ namespace std
       typedef num_put<_CharT, __ostreambuf_iter>        __numput_type;
       typedef ctype<_CharT>           			__ctype_type;
 
-      // 27.6.2.2 Constructor/destructor:
+      // [27.6.2.2] constructor/destructor
+      /**
+       *  @brief  Base constructor.
+       *
+       *  This ctor is almost never called by the user directly, rather from
+       *  derived classes' initialization lists, which pass a pointer to
+       *  their own stream buffer.
+      */
       explicit 
       basic_ostream(__streambuf_type* __sb)
       { this->init(__sb); }
 
+      /**
+       *  @brief  Base destructor.
+       *
+       *  This does very little apart from providing a virtual base dtor.
+      */
       virtual 
       ~basic_ostream() { }
 
-      // 27.6.2.3 Prefix/suffix:
+      // [27.6.2.3] prefix/suffix
       class sentry;
       friend class sentry;
       
-      // 27.6.2.5 Formatted output:
-      // 27.6.2.5.3  basic_ostream::operator<<
+      // [27.6.2.5] formatted output
+      // [27.6.2.5.3]  basic_ostream::operator<<
+      //@{
+      /**
+       *  @brief  Interface for manipulators.
+       *
+       *  Manuipulators such as @c std::endl and @c std::hex use these
+       *  functions in constructs like "std::cout << std::endl".  For more
+       *  information, see the iomanip header.
+      */
       __ostream_type&
       operator<<(__ostream_type& (*__pf)(__ostream_type&));
       
@@ -88,8 +115,35 @@ namespace std
       
       __ostream_type&
       operator<<(ios_base& (*__pf) (ios_base&));
-
-      // 27.6.2.5.2 Arithmetic Inserters
+      //@}
+
+      // [27.6.2.5.2] arithmetic inserters
+      /**
+       *  @name Arithmetic Inserters
+       *
+       *  All the @c operator<< functions (aka <em>formatted output
+       *  functions</em>) have some common behavior.  Each starts by
+       *  constructing a temporary object of type std::basic_ostream::sentry.
+       *  This can have several effects, concluding with the setting of a
+       *  status flag; see the sentry documentation for more.
+       *
+       *  If the sentry status is good, the function tries to generate
+       *  whatever data is appropriate for the type of the argument.
+       *
+       *  If an exception is thrown during insertion, ios_base::badbit
+       *  will be turned on in the stream's error state without causing an
+       *  ios_base::failure to be thrown.  The original exception will then
+       *  be rethrown.
+      */
+      //@{
+      /**
+       *  @brief  Basic arithmetic inserters
+       *  @param  A variable of builtin type.
+       *  @return  @c *this if successful
+       *
+       *  These functions use the stream's current locale (specifically, the
+       *  @c num_get facet) to perform numeric formatting.
+      */
       __ostream_type& 
       operator<<(long __n);
       
@@ -150,31 +204,140 @@ namespace std
       __ostream_type& 
       operator<<(const void* __p);
 
+      /**
+       *  @brief  Extracting from another streambuf.
+       *  @param  sb  A pointer to a streambuf
+       *
+       *  This function behaves like one of the basic arithmetic extractors,
+       *  in that it also constructs a sentry onject and has the same error
+       *  handling behavior.
+       *
+       *  If @a sb is NULL, the stream will set failbit in its error state.
+       *
+       *  Characters are extracted from @a sb and inserted into @c *this
+       *  until one of the following occurs:
+       *
+       *  - the input stream reaches end-of-file,
+       *  - insertion into the output sequence fails (in this case, the
+       *    character that would have been inserted is not extracted), or
+       *  - an exception occurs while getting a character from @a sb, which
+       *    sets failbit in the error state
+       *
+       *  If the function inserts no characters, failbit is set.
+      */
       __ostream_type& 
       operator<<(__streambuf_type* __sb);
-
-      // Unformatted output:
+      //@}
+
+      // [27.6.2.6] unformatted output functions
+      /**
+       *  @name Unformatted Output Functions
+       *
+       *  All the unformatted output functions have some common behavior.
+       *  Each starts by constructing a temporary object of type
+       *  std::basic_ostream::sentry.  This has several effects, concluding
+       *  with the setting of a status flag; see the sentry documentation
+       *  for more.
+       *
+       *  If the sentry status is good, the function tries to generate
+       *  whatever data is appropriate for the type of the argument.
+       *
+       *  If an exception is thrown during insertion, ios_base::badbit
+       *  will be turned on in the stream's error state.  If badbit is on in
+       *  the stream's exceptions mask, the exception will be rethrown
+       *  without completing its actions.
+      */
+      //@{
+      /**
+       *  @brief  Simple insertion.
+       *  @param  c  The character to insert.
+       *  @return  *this
+       *
+       *  Tries to insert @a c.
+       *
+       *  @note  This function is not overloaded on signed char and
+       *         unsigned char.
+      */
       __ostream_type& 
       put(char_type __c);
 
+      /**
+       *  @brief  Character string insertion.
+       *  @param  s  The array to insert.
+       *  @param  n  Maximum number of characters to insert.
+       *  @return  *this
+       *
+       *  Characters are copied from @a s and inserted into the stream until
+       *  one of the following happens:
+       *
+       *  - @a n characters are inserted
+       *  - inserting into the output sequence fails (in this case, badbit
+       *    will be set in the stream's error state)
+       *
+       *  @note  This function is not overloaded on signed char and
+       *         unsigned char.
+      */
       __ostream_type& 
       write(const char_type* __s, streamsize __n);
-
+      //@}
+
+      /**
+       *  @brief  Synchronizing the stream buffer.
+       *  @return  *this
+       *
+       *  If @c rdbuf() is a null pointer, changes nothing.
+       *
+       *  Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1,
+       *  sets badbit.
+      */
       __ostream_type& 
       flush();
 
-      // Seeks:
+      // [27.6.2.4] seek members
+      /**
+       *  @brief  Getting the current write position.
+       *  @return  A file position object.
+       *
+       *  If @c fail() is not false, returns @c pos_type(-1) to indicate
+       *  failure.  Otherwise returns @c rdbuf()->pubseekoff(0,cur,out).
+      */
       pos_type 
       tellp();
 
+      /**
+       *  @brief  Changing the current write position.
+       *  @param  pos  A file position object.
+       *  @return  *this
+       *
+       *  If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos).  If
+       *  that function fails, sets failbit.
+      */
       __ostream_type& 
       seekp(pos_type);
 
-      __ostream_type& 
+      /**
+       *  @brief  Changing the current write position.
+       *  @param  off  A file offset object.
+       *  @param  dir  The direction in which to seek.
+       *  @return  *this
+       *
+       *  If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir).
+       *  If that function fails, sets failbit.
+      */
+       __ostream_type& 
       seekp(off_type, ios_base::seekdir);
     };
 
-  // 27.6.2.3  Class basic_ostream::sentry
+  /**
+   *  @brief  Performs setup work for output streams.
+   *
+   *  Objects of this class are created before all of the standard
+   *  inserters are run.  It is responsible for "exception-safe prefix and
+   *  suffix operations."  Additional actions may be added by the
+   *  implementation, and we list them in
+   *  http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#5
+   *  under [27.6] notes.
+  */
   template <typename _CharT, typename _Traits>
     class basic_ostream<_CharT, _Traits>::sentry
     {
@@ -183,9 +346,27 @@ namespace std
       basic_ostream<_CharT,_Traits>& 	_M_os;
       
     public:
+      /**
+       *  @brief  The constructor performs preparatory work.
+       *  @param  os  The output stream to guard.
+       *
+       *  If the stream state is good (@a os.good() is true), then if the
+       *  stream is tied to another output stream, @c is.tie()->flush()
+       *  is called to synchronize the output sequences.
+       *
+       *  If the stream state is still good, then the sentry state becomes
+       *  true ("okay").
+      */
       explicit
       sentry(basic_ostream<_CharT,_Traits>& __os);
 
+      /**
+       *  @brief  Possibly flushes the stream.
+       *
+       *  If @c ios_base::unitbuf is set in @c os.flags(), and
+       *  @c std::uncaught_exception() is true, the sentry destructor calls
+       *  @c flush() on the output stream.
+      */
       ~sentry()
       {
 	// XXX MT
@@ -197,10 +378,34 @@ namespace std
 	  }
       }
 
+      /**
+       *  @brief  Quick status checking.
+       *  @return  The sentry state.
+       *
+       *  For ease of use, sentries may be converted to booleans.  The
+       *  return value is that of the sentry state (true == okay).
+      */
       operator bool() 
       { return _M_ok; }
     };
 
+  // [27.6.2.5.4] character insertion templates
+  //@{
+  /**
+   *  @brief  Character inserters
+   *  @param  out  An output stream.
+   *  @param  c  A character.
+   *  @return  out
+   *
+   *  Behaves like one of the formatted arithmetic inserters described in
+   *  std::basic_ostream.  After constructing a sentry object with good
+   *  status, this function inserts a single character and any required
+   *  padding (as determined by [22.2.2.2.2]).  @c out.width(0) is then
+   *  called.
+   *
+   *  If @a c is of type @c char and the character type of the stream is not
+   *  @c char, the character is widened before insertion.
+  */
   template<typename _CharT, typename _Traits>
     basic_ostream<_CharT, _Traits>&
     operator<<(basic_ostream<_CharT, _Traits>& __out, _CharT __c);
@@ -225,7 +430,22 @@ namespace std
     basic_ostream<char, _Traits>&
     operator<<(basic_ostream<char, _Traits>& __out, unsigned char __c)
     { return (__out << static_cast<char>(__c)); }
+  //@}
   
+  //@{
+  /**
+   *  @brief  String inserters
+   *  @param  out  An output stream.
+   *  @param  s  A character string.
+   *  @return  out
+   *  @pre  @a s must be a non-NULL pointer
+   *
+   *  Behaves like one of the formatted arithmetic inserters described in
+   *  std::basic_ostream.  After constructing a sentry object with good
+   *  status, this function inserts @c traits::length(s) characters starting
+   *  at @a s, widened if necessary, followed by any required padding (as
+   *  determined by [22.2.2.2.2]).  @c out.width(0) is then called.
+  */
   template<typename _CharT, typename _Traits>
     basic_ostream<_CharT, _Traits>&
     operator<<(basic_ostream<_CharT, _Traits>& __out, const _CharT* __s);
@@ -249,18 +469,38 @@ namespace std
     basic_ostream<char, _Traits> &
     operator<<(basic_ostream<char, _Traits>& __out, const unsigned char* __s)
     { return (__out << reinterpret_cast<const char*>(__s)); }
-
-  // 27.6.2.7 Standard basic_ostream manipulators
+  //@}
+
+  // [27.6.2.7] standard basic_ostream manipulators
+  /**
+   *  @brief  Write a newline and flush the stream.
+   *
+   *  This manipulator is often mistakenly used when a simple newline is
+   *  desired, leading to poor buffering performance.  See
+   *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2 for more
+   *  on this subject.
+  */
   template<typename _CharT, typename _Traits>
     basic_ostream<_CharT, _Traits>& 
     endl(basic_ostream<_CharT, _Traits>& __os)
     { return flush(__os.put(__os.widen('\n'))); }
 
+  /**
+   *  @brief  Write a null character into the output sequence.
+   *
+   *  "Null character" is @c CharT() by definition.  For CharT of @c char,
+   *  this correctly writes the ASCII @c NUL character string terminator.
+  */
   template<typename _CharT, typename _Traits>
     basic_ostream<_CharT, _Traits>& 
     ends(basic_ostream<_CharT, _Traits>& __os)
     { return __os.put(_CharT()); }
   
+  /**
+   *  @brief  Flushes the output stream.
+   *
+   *  This manipulator simply calls the stream's @c flush() member function.
+  */
   template<typename _CharT, typename _Traits>
     basic_ostream<_CharT, _Traits>& 
     flush(basic_ostream<_CharT, _Traits>& __os)
diff --git a/libstdc++-v3/include/std/std_sstream.h b/libstdc++-v3/include/std/std_sstream.h
index 6ee75053148..aaec83f082b 100644
--- a/libstdc++-v3/include/std/std_sstream.h
+++ b/libstdc++-v3/include/std/std_sstream.h
@@ -46,6 +46,18 @@
 
 namespace std
 {
+  // [27.7.1] template class basic_stringbuf
+  /**
+   *  @brief  The actual work of input and output (for std::string).
+   *
+   *  This class associates either or both of its input and output sequences
+   *  with a sequence of characters, which can be initialized from, or made
+   *  available as, a @c std::basic_string.  (Paraphrased from [27.7.1]/1.)
+   *
+   *  For this class, open modes (of type @c ios_base::openmode) have
+   *  @c in set if the input sequence can be read, and @c out set if the
+   *  output sequence can be written.
+  */
   template<typename _CharT, typename _Traits, typename _Alloc>
     class basic_stringbuf : public basic_streambuf<_CharT, _Traits>
     {
@@ -61,22 +73,48 @@ namespace std
       typedef typename traits_type::pos_type 		pos_type;
       typedef typename traits_type::off_type 		off_type;
 
-      // Non-standard Types:
+      //@{
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       typedef basic_streambuf<char_type, traits_type>  	__streambuf_type;
       typedef basic_string<char_type, _Traits, _Alloc> 	__string_type;
       typedef typename __string_type::size_type		__size_type;
+      //@}
 
     protected:
       // Data Members:
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       __string_type 		_M_string;
 
     public:
       // Constructors:
+      /**
+       *  @brief  Starts with an empty string buffer.
+       *  @param  mode  Whether the buffer can read, or write, or both.
+       *
+       *  The default constructor initializes the parent class using its
+       *  own default ctor.
+      */
       explicit
       basic_stringbuf(ios_base::openmode __mode = ios_base::in | ios_base::out)
       : __streambuf_type(), _M_string()
       { _M_stringbuf_init(__mode); }
 
+      /**
+       *  @brief  Starts with an existing string buffer.
+       *  @param  str  A string to copy as a starting buffer.
+       *  @param  mode  Whether the buffer can read, or write, or both.
+       *
+       *  This constructor initializes the parent class using its
+       *  own default ctor.
+      */
       explicit
       basic_stringbuf(const __string_type& __str,
 		      ios_base::openmode __mode = ios_base::in | ios_base::out)
@@ -84,6 +122,14 @@ namespace std
       { _M_stringbuf_init(__mode); }
 
       // Get and set:
+      /**
+       *  @brief  Copying out the string buffer.
+       *  @return  A copy of one of the underlying sequences.
+       *
+       *  "If the buffer is only created in input mode, the underlying
+       *  character sequence is equal to the input sequence; otherwise, it
+       *  is equal to the output sequence." [27.7.1.2]/1
+      */
       __string_type
       str() const
       {
@@ -102,6 +148,13 @@ namespace std
 	  return _M_string;
       }
 
+      /**
+       *  @brief  Setting a new buffer.
+       *  @param  s  The string to use as a new sequence.
+       *
+       *  Deallocates any previous stored sequence, then copies @a s to
+       *  use as a new one.
+      */
       void
       str(const __string_type& __s)
       {
@@ -112,6 +165,11 @@ namespace std
 
     protected:
       // Common initialization code for both ctors goes here.
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       void
       _M_stringbuf_init(ios_base::openmode __mode)
       {
@@ -135,6 +193,7 @@ namespace std
       }
 
       // Overridden virtual functions:
+      // [documentation is inherited]
       virtual int_type
       underflow()
       {
@@ -144,12 +203,25 @@ namespace std
 	  return traits_type::eof();
       }
 
+      // [documentation is inherited]
       virtual int_type
       pbackfail(int_type __c = traits_type::eof());
 
+      // [documentation is inherited]
       virtual int_type
       overflow(int_type __c = traits_type::eof());
 
+      /**
+       *  @brief  Manipulates the buffer.
+       *  @param  s  Pointer to a buffer area.
+       *  @param  n  Size of @a s.
+       *  @return  @c this
+       *
+       *  If no buffer has already been created, and both @a s and @a n are
+       *  non-zero, then @c s is used as a buffer; see
+       *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2
+       *  for more.
+      */
       virtual __streambuf_type*
       setbuf(char_type* __s, streamsize __n)
       {
@@ -161,10 +233,12 @@ namespace std
 	return this;
       }
 
+      // [documentation is inherited]
       virtual pos_type
       seekoff(off_type __off, ios_base::seekdir __way,
 	      ios_base::openmode __mode = ios_base::in | ios_base::out);
 
+      // [documentation is inherited]
       virtual pos_type
       seekpos(pos_type __sp,
 	      ios_base::openmode __mode = ios_base::in | ios_base::out);
@@ -175,6 +249,11 @@ namespace std
       // Assumes: contents of _M_string and internal buffer match exactly.
       // __i == _M_in_cur - _M_in_beg
       // __o == _M_out_cur - _M_out_beg
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       virtual int
       _M_really_sync(__size_type __i, __size_type __o)
       {
@@ -196,7 +275,15 @@ namespace std
     };
 
 
-  // 27.7.2  Template class basic_istringstream
+  // [27.7.2] Template class basic_istringstream
+  /**
+   *  @brief  Controlling input for std::string.
+   *
+   *  This class supports reading from objects of type std::basic_string,
+   *  using the inherited functions from std::basic_istream.  To control
+   *  the associated sequence, an instance of std::basic_stringbuf is used,
+   *  which this page refers to as @c sb.
+  */
   template<typename _CharT, typename _Traits, typename _Alloc>
     class basic_istringstream : public basic_istream<_CharT, _Traits>
     {
@@ -218,40 +305,104 @@ namespace std
       typedef basic_istream<char_type, traits_type>	__istream_type;
 
     private:
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       __stringbuf_type	_M_stringbuf;
 
     public:
       // Constructors:
+      /**
+       *  @brief  Default constructor starts with an empty string buffer.
+       *  @param  mode  Whether the buffer can read, or write, or both.
+       *
+       *  @c ios_base::in is automatically included in @a mode.
+       *
+       *  Initializes @c sb using @c mode|in, and passes @c &sb to the base
+       *  class initializer.  Does not allocate any buffer.
+       *
+       *  @if maint
+       *  That's a lie.  We initialize the base class with NULL, because the
+       *  string class does its own memory management.
+       *  @endif
+      */
       explicit
       basic_istringstream(ios_base::openmode __mode = ios_base::in)
       : __istream_type(NULL), _M_stringbuf(__mode | ios_base::in)
       { this->init(&_M_stringbuf); }
 
+      /**
+       *  @brief  Starts with an existing string buffer.
+       *  @param  str  A string to copy as a starting buffer.
+       *  @param  mode  Whether the buffer can read, or write, or both.
+       *
+       *  @c ios_base::in is automatically included in @a mode.
+       *
+       *  Initializes @c sb using @a str and @c mode|in, and passes @c &sb
+       *  to the base class initializer.
+       *
+       *  @if maint
+       *  That's a lie.  We initialize the base class with NULL, because the
+       *  string class does its own memory management.
+       *  @endif
+      */
       explicit
       basic_istringstream(const __string_type& __str,
 			  ios_base::openmode __mode = ios_base::in)
       : __istream_type(NULL), _M_stringbuf(__str, __mode | ios_base::in)
       { this->init(&_M_stringbuf); }
 
+      /**
+       *  @brief  The destructor does nothing.
+       *
+       *  The buffer is deallocated by the stringbuf object, not the
+       *  formatting stream.
+      */
       ~basic_istringstream()
       { }
 
       // Members:
+      /**
+       *  @brief  Accessing the underlying buffer.
+       *  @return  The current basic_stringbuf buffer.
+       *
+       *  This hides both signatures of std::basic_ios::rdbuf().
+      */
       __stringbuf_type*
       rdbuf() const
       { return const_cast<__stringbuf_type*>(&_M_stringbuf); }
 
+      /**
+       *  @brief  Copying out the string buffer.
+       *  @return  @c rdbuf()->str()
+      */
       __string_type
       str() const
       { return _M_stringbuf.str(); }
 
+      /**
+       *  @brief  Setting a new buffer.
+       *  @param  s  The string to use as a new sequence.
+       *
+       *  Calls @c rdbuf()->str(s).
+      */
       void
       str(const __string_type& __s)
       { _M_stringbuf.str(__s); }
     };
 
 
-  // 27.7.3  Template class basic_ostringstream
+  // [27.7.3] Template class basic_ostringstream
+  /**
+   *  @brief  Controlling output for std::string.
+   *
+   *  This class supports writing to objects of type std::basic_string,
+   *  using the inherited functions from std::basic_ostream.  To control
+   *  the associated sequence, an instance of std::basic_stringbuf is used,
+   *  which this page refers to as @c sb.
+  */
   template <typename _CharT, typename _Traits, typename _Alloc>
     class basic_ostringstream : public basic_ostream<_CharT, _Traits>
     {
@@ -273,40 +424,104 @@ namespace std
       typedef basic_ostream<char_type, traits_type>	__ostream_type;
 
     private:
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       __stringbuf_type	_M_stringbuf;
 
     public:
-     // Constructors/destructor:
+      // Constructors/destructor:
+      /**
+       *  @brief  Default constructor starts with an empty string buffer.
+       *  @param  mode  Whether the buffer can read, or write, or both.
+       *
+       *  @c ios_base::out is automatically included in @a mode.
+       *
+       *  Initializes @c sb using @c mode|out, and passes @c &sb to the base
+       *  class initializer.  Does not allocate any buffer.
+       *
+       *  @if maint
+       *  That's a lie.  We initialize the base class with NULL, because the
+       *  string class does its own memory management.
+       *  @endif
+      */
       explicit
       basic_ostringstream(ios_base::openmode __mode = ios_base::out)
       : __ostream_type(NULL), _M_stringbuf(__mode | ios_base::out)
       { this->init(&_M_stringbuf); }
 
+      /**
+       *  @brief  Starts with an existing string buffer.
+       *  @param  str  A string to copy as a starting buffer.
+       *  @param  mode  Whether the buffer can read, or write, or both.
+       *
+       *  @c ios_base::out is automatically included in @a mode.
+       *
+       *  Initializes @c sb using @a str and @c mode|out, and passes @c &sb
+       *  to the base class initializer.
+       *
+       *  @if maint
+       *  That's a lie.  We initialize the base class with NULL, because the
+       *  string class does its own memory management.
+       *  @endif
+      */
       explicit
       basic_ostringstream(const __string_type& __str,
 			  ios_base::openmode __mode = ios_base::out)
       : __ostream_type(NULL), _M_stringbuf(__str, __mode | ios_base::out)
       { this->init(&_M_stringbuf); }
 
+      /**
+       *  @brief  The destructor does nothing.
+       *
+       *  The buffer is deallocated by the stringbuf object, not the
+       *  formatting stream.
+      */
       ~basic_ostringstream()
       { }
 
       // Members:
+      /**
+       *  @brief  Accessing the underlying buffer.
+       *  @return  The current basic_stringbuf buffer.
+       *
+       *  This hides both signatures of std::basic_ios::rdbuf().
+      */
       __stringbuf_type*
       rdbuf() const
       { return const_cast<__stringbuf_type*>(&_M_stringbuf); }
 
+      /**
+       *  @brief  Copying out the string buffer.
+       *  @return  @c rdbuf()->str()
+      */
       __string_type
       str() const
       { return _M_stringbuf.str(); }
 
+      /**
+       *  @brief  Setting a new buffer.
+       *  @param  s  The string to use as a new sequence.
+       *
+       *  Calls @c rdbuf()->str(s).
+      */
       void
       str(const __string_type& __s)
       { _M_stringbuf.str(__s); }
     };
 
 
-  // 27.7.4  Template class basic_stringstream
+  // [27.7.4] Template class basic_stringstream
+  /**
+   *  @brief  Controlling input and output for std::string.
+   *
+   *  This class supports reading from and writing to objects of type
+   *  std::basic_string, using the inherited functions from
+   *  std::basic_iostream.  To control the associated sequence, an instance
+   *  of std::basic_stringbuf is used, which this page refers to as @c sb.
+  */
   template <typename _CharT, typename _Traits, typename _Alloc>
     class basic_stringstream : public basic_iostream<_CharT, _Traits>
     {
@@ -328,33 +543,85 @@ namespace std
       typedef basic_iostream<char_type, traits_type>	__iostream_type;
 
     private:
+      /**
+       *  @if maint
+       *  @doctodo
+       *  @endif
+      */
       __stringbuf_type	_M_stringbuf;
 
     public:
       // Constructors/destructors
+      /**
+       *  @brief  Default constructor starts with an empty string buffer.
+       *  @param  mode  Whether the buffer can read, or write, or both.
+       *
+       *  Initializes @c sb using @c mode, and passes @c &sb to the base
+       *  class initializer.  Does not allocate any buffer.
+       *
+       *  @if maint
+       *  That's a lie.  We initialize the base class with NULL, because the
+       *  string class does its own memory management.
+       *  @endif
+      */
       explicit
       basic_stringstream(ios_base::openmode __m = ios_base::out | ios_base::in)
       : __iostream_type(NULL), _M_stringbuf(__m)
       { this->init(&_M_stringbuf); }
 
+      /**
+       *  @brief  Starts with an existing string buffer.
+       *  @param  str  A string to copy as a starting buffer.
+       *  @param  mode  Whether the buffer can read, or write, or both.
+       *
+       *  Initializes @c sb using @a str and @c mode, and passes @c &sb
+       *  to the base class initializer.
+       *
+       *  @if maint
+       *  That's a lie.  We initialize the base class with NULL, because the
+       *  string class does its own memory management.
+       *  @endif
+      */
       explicit
       basic_stringstream(const __string_type& __str,
 			 ios_base::openmode __m = ios_base::out | ios_base::in)
       : __iostream_type(NULL), _M_stringbuf(__str, __m)
       { this->init(&_M_stringbuf); }
 
+      /**
+       *  @brief  The destructor does nothing.
+       *
+       *  The buffer is deallocated by the stringbuf object, not the
+       *  formatting stream.
+      */
       ~basic_stringstream()
       { }
 
       // Members:
+      /**
+       *  @brief  Accessing the underlying buffer.
+       *  @return  The current basic_stringbuf buffer.
+       *
+       *  This hides both signatures of std::basic_ios::rdbuf().
+      */
       __stringbuf_type*
       rdbuf() const
       { return const_cast<__stringbuf_type*>(&_M_stringbuf); }
 
+      /**
+       *  @brief  Copying out the string buffer.
+       *  @return  @c rdbuf()->str()
+      */
       __string_type
       str() const
       { return _M_stringbuf.str(); }
 
+      /**
+       *  @brief  Setting a new buffer.
+       *  @param  s  The string to use as a new sequence.
+       *
+       *  Calls @c rdbuf()->str(s).
+      */
       void
       str(const __string_type& __s)
       { _M_stringbuf.str(__s); }
diff --git a/libstdc++-v3/include/std/std_streambuf.h b/libstdc++-v3/include/std/std_streambuf.h
index ecd546e85a8..883401bf6ee 100644
--- a/libstdc++-v3/include/std/std_streambuf.h
+++ b/libstdc++-v3/include/std/std_streambuf.h
@@ -50,28 +50,104 @@
 
 namespace std
 {
+  /**
+   *  @if maint
+   *  Does stuff.
+   *  @endif
+  */
   template<typename _CharT, typename _Traits>
     streamsize
     __copy_streambufs(basic_ios<_CharT, _Traits>& _ios,
 		      basic_streambuf<_CharT, _Traits>* __sbin,
 		      basic_streambuf<_CharT, _Traits>* __sbout);
   
-  // 27.5.2 Template class basic_streambuf<_CharT, _Traits>
+  /**
+   *  @brief  The actual work of input and output (interface).
+   *
+   *  This is a base class.  Derived stream buffers each control a
+   *  pair of character sequences:  one for input, and one for output.
+   *
+   *  Section [27.5.1] of the standard describes the requirements and
+   *  behavior of stream buffer classes.  That section (three paragraphs)
+   *  is reproduced here, for simplicity and accuracy.
+   *
+   *  -# Stream buffers can impose various constraints on the sequences
+   *     they control.  Some constraints are:
+   *     - The controlled input sequence can be not readable.
+   *     - The controlled output sequence can be not writable.
+   *     - The controlled sequences can be associated with the contents of
+   *       other representations for character sequences, such as external
+   *       files.
+   *     - The controlled sequences can support operations @e directly to or
+   *       from associated sequences.
+   *     - The controlled sequences can impose limitations on how the
+   *       program can read characters from a sequence, write characters to
+   *       a sequence, put characters back into an input sequence, or alter
+   *       the stream position.
+   *     .
+   *  -# Each sequence is characterized by three pointers which, if non-null,
+   *     all point into the same @c charT array object.  The array object
+   *     represents, at any moment, a (sub)sequence of characters from the
+   *     sequence.  Operations performed on a sequence alter the values
+   *     stored in these pointers, perform reads and writes directly to or
+   *     from associated sequences, and alter "the stream position" and
+   *     conversion state as needed to maintain this subsequence relationship.
+   *     The three pointers are:
+   *     - the <em>beginning pointer</em>, or lowest element address in the
+   *       array (called @e xbeg here);
+   *     - the <em>next pointer</em>, or next element address that is a
+   *       current candidate for reading or writing (called @e xnext here);
+   *     - the <em>end pointer</em>, or first element address beyond the
+   *       end of the array (called @e xend here).
+   *     .
+   *  -# The following semantic constraints shall always apply for any set
+   *     of three pointers for a sequence, using the pointer names given
+   *     immediately above:
+   *     - If @e xnext is not a null pointer, then @e xbeg and @e xend shall
+   *       also be non-null pointers into the same @c charT array, as
+   *       described above; otherwise, @e xbeg and @e xend shall also be null.
+   *     - If @e xnext is not a null pointer and @e xnext < @e xend for an
+   *       output sequence, then a <em>write position</em> is available.
+   *       In this case, @e *xnext shall be assignable as the next element
+   *       to write (to put, or to store a character value, into the sequence).
+   *     - If @e xnext is not a null pointer and @e xbeg < @e xnext for an
+   *       input sequence, then a <em>putback position</em> is available.
+   *       In this case, @e xnext[-1] shall have a defined value and is the
+   *       next (preceding) element to store a character that is put back
+   *       into the input sequence.
+   *     - If @e xnext is not a null pointer and @e xnext< @e xend for an
+   *       input sequence, then a <em>read position</em> is available.
+   *       In this case, @e *xnext shall have a defined value and is the
+   *       next element to read (to get, or to obtain a character value,
+   *       from the sequence).
+  */
   template<typename _CharT, typename _Traits>
     class basic_streambuf 
     {
     public:
-      // Types:
+      //@{
+      /**
+       *  These are standard types.  They permit a standardized way of
+       *  referring to names of (or names dependant on) the template
+       *  parameters, which are specific to the implementation.
+      */
       typedef _CharT 					char_type;
       typedef _Traits 					traits_type;
       typedef typename traits_type::int_type 		int_type;
       typedef typename traits_type::pos_type 		pos_type;
       typedef typename traits_type::off_type 		off_type;
-
-      // Non-standard Types:
+      //@}
+
+      //@{
+      /**
+       *  @if maint
+       *  These are non-standard types.
+       *  @endif
+      */
       typedef ctype<char_type>           		__ctype_type;
       typedef basic_streambuf<char_type, traits_type>  	__streambuf_type;
       typedef typename traits_type::state_type 		__state_type;
+      //@}
       
       friend class basic_ios<char_type, traits_type>;
       friend class basic_istream<char_type, traits_type>;
@@ -84,56 +160,100 @@ namespace std
 			  __streambuf_type* __sbin,__streambuf_type* __sbout);
       
     protected:
-      // Pointer to the beginning of internally-allocated
-      // space. Filebuf manually allocates/deallocates this, whereas
-      // stringstreams attempt to use the built-in intelligence of the
-      // string class. If you are managing memory, set this. If not,
-      // leave it NULL.
+      /**
+       *  @if maint
+       *  Pointer to the beginning of internally-allocated space.  Filebuf
+       *  manually allocates/deallocates this, whereas stringstreams attempt
+       *  to use the built-in intelligence of the string class.  If you are
+       *  managing memory, set this.  If not, leave it NULL.
+       *  @endif
+      */
       char_type*		_M_buf; 	
 
-      // Actual size of allocated internal buffer, in bytes.
+      /**
+       *  @if maint
+       *  Actual size of allocated internal buffer, in bytes.
+       *  @endif
+      */
       size_t			_M_buf_size;
 
-      // Optimal or preferred size of internal buffer, in bytes.
+      /**
+       *  @if maint
+       *  Optimal or preferred size of internal buffer, in bytes.
+       *  @endif
+      */
       size_t			_M_buf_size_opt;
 
-      // True iff _M_in_* and _M_out_* buffers should always point to
-      // the same place.  True for fstreams, false for sstreams.
+      /**
+       *  @if maint
+       *  True iff _M_in_* and _M_out_* buffers should always point to
+       *  the same place.  True for fstreams, false for sstreams.
+       *  @endif
+      */
       bool 			_M_buf_unified;	
 
-      // 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
-      // put == output == write
+      //@{
+      /**
+       *  @if maint
+       *  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
+       *  -  put == output == write
+       *  @endif
+      */
       char_type* 		_M_in_beg;  	// Start of get area. 
       char_type* 		_M_in_cur;	// Current read area. 
       char_type* 		_M_in_end;	// End of get area. 
       char_type* 		_M_out_beg; 	// Start of put area. 
       char_type* 		_M_out_cur;  	// Current put area. 
       char_type* 		_M_out_end;  	// End of put area. 
+      //@}
 
-      // Place to stash in || out || in | out settings for current streambuf.
+      /**
+       *  @if maint
+       *  Place to stash in || out || in | out settings for current streambuf.
+       *  @endif
+      */
       ios_base::openmode 	_M_mode;	
 
-      // Current locale setting.
+      /**
+       *  @if maint
+       *  Current locale setting.
+       *  @endif
+      */
       locale 			_M_buf_locale;	
 
-      // True iff locale is initialized.
+      /**
+       *  @if maint
+       *  True iff locale is initialized.
+       *  @endif
+      */
       bool 			_M_buf_locale_init;
 
-      // Necessary bits for putback buffer management. Only used in
-      // the basic_filebuf class, as necessary for the standard
-      // requirements. The only basic_streambuf member function that
-      // needs access to these data members is in_avail...
-      // NB: pbacks of over one character are not currently supported.
+      //@{
+      /**
+       *  @if maint
+       *  Necessary bits for putback buffer management. Only used in
+       *  the basic_filebuf class, as necessary for the standard
+       *  requirements. The only basic_streambuf member function that
+       *  needs access to these data members is in_avail...
+       *  
+       *  @note pbacks of over one character are not currently supported.
+       *  @endif
+      */
       static const size_t   	_S_pback_size = 1; 
       char_type			_M_pback[_S_pback_size]; 
       char_type*		_M_pback_cur_save;
       char_type*		_M_pback_end_save;
       bool			_M_pback_init; 
+      //@}
 
-      // Yet unused.
+      /**
+       *  @if maint
+       *  Yet unused.
+       *  @endif
+      */
       fpos<__state_type>	_M_pos;
 
       // Initializes pback buffers, and moves normal buffers to safety.
@@ -236,6 +356,7 @@ namespace std
       }
 
   public:
+      /// Destructor deallocates no buffer space.
       virtual 
       ~basic_streambuf() 
       {
@@ -246,7 +367,14 @@ namespace std
 	_M_buf_locale_init = false;
       }
 
-      // Locales:
+      // [27.5.2.2.1] locales
+      /**
+       *  @brief  Entry point for imbue().
+       *  @param  loc  The new locale.
+       *  @return  The previous locale.
+       *
+       *  Calls the derived imbue(loc).
+      */
       locale 
       pubimbue(const locale &__loc)
       {
@@ -255,6 +383,14 @@ namespace std
 	return __tmp;
       }
 
+      /**
+       *  @brief  Locale access.
+       *  @return  The current locale in effect.
+       *
+       *  If pubimbue(loc) has been called, then the most recent @c loc
+       *  is returned.  Otherwise the global locale in effect at the time
+       *  of construction is returned.
+      */
       locale   
       getloc() const
       {
@@ -264,7 +400,15 @@ namespace std
 	  return locale();
       } 
 
-      // Buffer and positioning:
+      // [27.5.2.2.2] buffer management and positioning
+      //@{
+      /**
+       *  @brief  Entry points for derived buffer functions.
+       *
+       *  The public versions of @c pubfoo dispatch to the protected
+       *  derived @c foo member functions, passing the arguments (if any)
+       *  and returning the result unchanged.
+      */
       __streambuf_type* 
       pubsetbuf(char_type* __s, streamsize __n) 
       { return this->setbuf(__s, __n); }
@@ -281,9 +425,17 @@ namespace std
 
       int 
       pubsync() { return this->sync(); }
-
-      // Get and put areas:
-      // Get area:
+      //@}
+
+      // [27.5.2.2.3] get area
+      /**
+       *  @brief  Looking ahead into the stream.
+       *  @return  The number of characters available.
+       *
+       *  If a read position is available, returns the number of characters
+       *  available for reading before the buffer must be refilled.
+       *  Otherwise returns the derived @c showmanyc().
+      */
       streamsize 
       in_avail() 
       { 
@@ -304,6 +456,13 @@ namespace std
 	return __ret;
       }
 
+      /**
+       *  @brief  Getting the next character.
+       *  @return  The next character, or eof.
+       *
+       *  Calls @c sbumpc(), and if that function returns
+       *  @c traits::eof(), so does this function.  Otherwise, @c sgetc().
+      */
       int_type 
       snextc()
       {
@@ -312,9 +471,25 @@ namespace std
 		? __eof : this->sgetc());
       }
 
+      /**
+       *  @brief  Getting the next character.
+       *  @return  The next character, or eof.
+       *
+       *  If the input read position is available, returns that character
+       *  and increments the read pointer, otherwise calls and returns
+       *  @c uflow().
+      */
       int_type 
       sbumpc();
 
+      /**
+       *  @brief  Getting the next character.
+       *  @return  The next character, or eof.
+       *
+       *  If the input read position is available, returns that character,
+       *  otherwise calls and returns @c underflow().  Does not move the 
+       *  read position after fetching the character.
+      */
       int_type 
       sgetc()
       {
@@ -326,26 +501,84 @@ namespace std
 	return __ret;
       }
 
+      /**
+       *  @brief  Entry point for xsgetn.
+       *  @param  s  A buffer area.
+       *  @param  n  A count.
+       *
+       *  Returns xsgetn(s,n).  The effect is to fill @a s[0] through
+       *  @a s[n-1] with characters from the input sequence, if possible.
+      */
       streamsize 
       sgetn(char_type* __s, streamsize __n)
       { return this->xsgetn(__s, __n); }
 
-      // Putback:
+      // [27.5.2.2.4] putback
+      /**
+       *  @brief  Pushing characters back into the input stream.
+       *  @param  c  The character to push back.
+       *  @return  The previous character, if possible.
+       *
+       *  Similar to sungetc(), but @a c is pushed onto the stream instead
+       *  of "the previous character".  If successful, the next character
+       *  fetched from the input stream will be @a c.
+      */
       int_type 
       sputbackc(char_type __c);
 
+      /**
+       *  @brief  Moving backwards in the input stream.
+       *  @return  The previous character, if possible.
+       *
+       *  If a putback position is available, this function decrements the
+       *  input pointer and returns that character.  Otherwise, calls and
+       *  returns pbackfail().  The effect is to "unget" the last character
+       *  "gotten".
+      */
       int_type 
       sungetc();
 
-      // Put area:
+      // [27.5.2.2.5] put area
+      /**
+       *  @brief  Entry point for all single-character output functions.
+       *  @param  c  A character to output.
+       *  @return  @a c, if possible.
+       *
+       *  One of two public output functions.
+       *
+       *  If a write position is available for the output sequence (i.e.,
+       *  the buffer is not full), stores @a c in that position, increments
+       *  the position, and returns @c traits::to_int_type(c).  If a write
+       *  position is not available, returns @c overflow(c).
+      */
       int_type 
       sputc(char_type __c);
 
+      /**
+       *  @brief  Entry point for all single-character output functions.
+       *  @param  s  A buffer read area.
+       *  @param  n  A count.
+       *
+       *  One of two public output functions.
+       *
+       *
+       *  Returns xsputn(s,n).  The effect is to write @a s[0] through
+       *  @a s[n-1] to the output sequence, if possible.
+      */
       streamsize 
       sputn(const char_type* __s, streamsize __n)
       { return this->xsputn(__s, __n); }
 
     protected:
+      /**
+       *  @brief  Base constructor.
+       *
+       *  Only called from derived constructors, and sets up all the
+       *  buffer data to zero, including the pointers described in the
+       *  basic_streambuf class description.  Note that, as a result,
+       *  - the class starts with no read nor write positions available,
+       *  - this is not an error
+      */
       basic_streambuf()
       : _M_buf(NULL), _M_buf_size(0), _M_buf_size_opt(BUFSIZ), 
       _M_buf_unified(false), _M_in_beg(0), _M_in_cur(0), _M_in_end(0), 
@@ -355,7 +588,18 @@ namespace std
       _M_pback_init(false)
       { }
 
-      // Get area:
+      // [27.5.2.3.1] get area access
+      //@{
+      /**
+       *  @brief  Access to the get area.
+       *
+       *  These functions are only available to other protected functions,
+       *  including derived classes.
+       *
+       *  - eback() returns the beginning pointer for the input sequence
+       *  - gptr() returns the next pointer for the input sequence
+       *  - egptr() returns the end pointer for the input sequence
+      */
       char_type* 
       eback() const { return _M_in_beg; }
 
@@ -364,10 +608,25 @@ namespace std
 
       char_type* 
       egptr() const { return _M_in_end; }
-
+      //@}
+
+      /**
+       *  @brief  Moving the read position.
+       *  @param  n  The delta by which to move.
+       *
+       *  This just advances the read position without returning any data.
+      */
       void 
       gbump(int __n) { _M_in_cur += __n; }
 
+      /**
+       *  @brief  Setting the three read area pointers.
+       *  @param  gbeg  A pointer.
+       *  @param  gnext  A pointer.
+       *  @param  gend  A pointer.
+       *  @post  @a gbeg == @c eback(), @a gnext == @c gptr(), and
+       *         @a gend == @c egptr()
+      */
       void 
       setg(char_type* __gbeg, char_type* __gnext, char_type* __gend)
       {
@@ -378,7 +637,18 @@ namespace std
 	  _M_mode = _M_mode | ios_base::in;
       }
 
-      // Put area:
+      // [27.5.2.3.2] put area access
+      //@{
+      /**
+       *  @brief  Access to the put area.
+       *
+       *  These functions are only available to other protected functions,
+       *  including derived classes.
+       *
+       *  - pbase() returns the beginning pointer for the output sequence
+       *  - pptr() returns the next pointer for the output sequence
+       *  - epptr() returns the end pointer for the output sequence
+      */
       char_type* 
       pbase() const { return _M_out_beg; }
 
@@ -387,10 +657,24 @@ namespace std
 
       char_type* 
       epptr() const { return _M_out_end; }
-
+      //@}
+
+      /**
+       *  @brief  Moving the write position.
+       *  @param  n  The delta by which to move.
+       *
+       *  This just advances the write position without returning any data.
+      */
       void 
       pbump(int __n) { _M_out_cur += __n; }
 
+      /**
+       *  @brief  Setting the three write area pointers.
+       *  @param  pbeg  A pointer.
+       *  @param  pend  A pointer.
+       *  @post  @a pbeg == @c pbase(), @a pbeg == @c pptr(), and
+       *         @a pend == @c epptr()
+      */
       void 
       setp(char_type* __pbeg, char_type* __pend)
       { 
@@ -400,8 +684,19 @@ namespace std
 	  _M_mode = _M_mode | ios_base::out;
       }
 
-      // Virtual functions:
-      // Locales:
+      // [27.5.2.4] virtual functions
+      // [27.5.2.4.1] locales
+      /**
+       *  @brief  Changes translations.
+       *  @param  loc  A new locale.
+       *
+       *  Translations done during I/O which depend on the current locale
+       *  are changed by this call.  The standard adds, "Between invocations
+       *  of this function a class derived from streambuf can safely cache
+       *  results of calls to locale functions and to members of facets
+       *  so obtained."  This function simply stores the new locale for use
+       *  by derived classes.
+      */
       virtual void 
       imbue(const locale& __loc) 
       { 
@@ -410,35 +705,126 @@ namespace std
 	  _M_buf_locale = __loc;
       }
 
-      // Buffer management and positioning:
+      // [27.5.2.4.2] buffer management and positioning
+      /**
+       *  @brief  Maniuplates the buffer.
+       *
+       *  Each derived class provides its own appropriate behavior.  See
+       *  the next-to-last paragraph of 
+       *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2 for
+       *  more on this function.
+       *
+       *  @note  Base class version does nothing, returns @c this.
+      */
       virtual basic_streambuf<char_type,_Traits>* 
       setbuf(char_type*, streamsize)
       {	return this; }
       
+      /**
+       *  @brief  Alters the stream positions.
+       *
+       *  Each derived class provides its own appropriate behavior.
+       *  @note  Base class version does nothing, returns a @c pos_type
+       *         that represents an invalid stream position.
+      */
       virtual pos_type 
       seekoff(off_type, ios_base::seekdir,
 	      ios_base::openmode /*__mode*/ = ios_base::in | ios_base::out)
       { return pos_type(off_type(-1)); } 
 
+      /**
+       *  @brief  Alters the stream positions.
+       *
+       *  Each derived class provides its own appropriate behavior.
+       *  @note  Base class version does nothing, returns a @c pos_type
+       *         that represents an invalid stream position.
+      */
       virtual pos_type 
       seekpos(pos_type, 
 	      ios_base::openmode /*__mode*/ = ios_base::in | ios_base::out)
       { return pos_type(off_type(-1)); } 
 
+      /**
+       *  @brief  Synchronizes the buffer arrays with the controlled sequences.
+       *  @return  -1 on failure.
+       *
+       *  Each derived class provides its own appropriate behavior,
+       *  including the definition of "failure".
+       *  @note  Base class version does nothing, returns zero.
+      */
       virtual int 
       sync() { return 0; }
 
-      // Get area:
+      // [27.5.2.4.3] get area
+      /**
+       *  @brief  Investigating the data available.
+       *  @return  An estimate of the number of characters available in the
+       *           input sequence, or -1.
+       *
+       *  "If it returns a positive value, then successive calls to
+       *  @c underflow() will not return @c traits::eof() until at least that
+       *  number of characters have been supplied.  If @c showmanyc()
+       *  returns -1, then calls to @c underflow() or @c uflow() will fail."
+       *  [27.5.2.4.3]/1
+       *
+       *  @note  Base class version does nothing, returns zero.
+       *  @note  The standard adds that "the intention is not only that the
+       *         calls [to underflow or uflow] will not return @c eof() but
+       *         that they will return "immediately".
+       *  @note  The standard adds that "the morphemes of @c showmanyc are
+       *         "es-how-many-see", not "show-manic".
+      */
       virtual streamsize 
       showmanyc() { return 0; }
 
+      /**
+       *  @brief  Multiple character extraction.
+       *  @param  s  A buffer area.
+       *  @param  n  Maximum number of characters to assign.
+       *  @return  The number of characters assigned.
+       *
+       *  Fills @a s[0] through @a s[n-1] with characters from the input
+       *  sequence, as if by @c sbumpc().  Stops when either @a n characters
+       *  have been copied, or when @c traits::eof() would be copied.
+       *
+       *  It is expected that derived classes provide a more efficient
+       *  implementation by overriding this definition.
+      */
       virtual streamsize 
       xsgetn(char_type* __s, streamsize __n);
 
+      /**
+       *  @brief  Fetches more data from the controlled sequence.
+       *  @return  The first character from the <em>pending sequence</em>.
+       *
+       *  Informally, this function is called when the input buffer is
+       *  exhausted (or does not exist, as buffering need not actually be
+       *  done).  If a buffer exists, it is "refilled".  In either case, the
+       *  next available character is returned, or @c traits::eof() to
+       *  indicate a null pending sequence.
+       *
+       *  For a formal definiton of the pending sequence, see a good text
+       *  such as Langer & Kreft, or [27.5.2.4.3]/7-14.
+       *
+       *  A functioning input streambuf can be created by overriding only
+       *  this function (no buffer area will be used).  For an example, see
+       *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#6
+       *
+       *  @note  Base class version does nothing, returns eof().
+      */
       virtual int_type 
       underflow()
       { return traits_type::eof(); }
 
+      /**
+       *  @brief  Fetches more data from the controlled sequence.
+       *  @return  The first character from the <em>pending sequence</em>.
+       *
+       *  Informally, this function does the same thing as @c underflow(),
+       *  and in fact is required to call that function.  It also returns
+       *  the new character, like @c underflow() does.  However, this
+       *  function also moves the read position forward by one.
+      */
       virtual int_type 
       uflow() 
       {
@@ -455,23 +841,78 @@ namespace std
 	return __ret;    
       }
 
-      // Putback:
+      // [27.5.2.4.4] putback
+      /**
+       *  @brief  Tries to back up the input sequence.
+       *  @param  c  The character to be inserted back into the sequence.
+       *  @return  eof() on failure, "some other value" on success
+       *  @post  The constraints of @c gptr(), @c eback(), and @c pptr()
+       *         are the same as for @c underflow().
+       *
+       *  @note  Base class version does nothing, returns eof().
+      */
       virtual int_type 
       pbackfail(int_type /* __c */  = traits_type::eof())
       { return traits_type::eof(); }
 
       // Put area:
+      /**
+       *  @brief  Multiple character insertion.
+       *  @param  s  A buffer area.
+       *  @param  n  Maximum number of characters to write.
+       *  @return  The number of characters written.
+       *
+       *  Writes @a s[0] through @a s[n-1] to the output sequence, as if
+       *  by @c sputc().  Stops when either @a n characters have been
+       *  copied, or when @c sputc() would return @c traits::eof().
+       *
+       *  It is expected that derived classes provide a more efficient
+       *  implementation by overriding this definition.
+      */
       virtual streamsize 
       xsputn(const char_type* __s, streamsize __n);
 
+      /**
+       *  @brief  Consumes data from the buffer; writes to the
+       *          controlled sequence.
+       *  @param  c  An additional character to consume.
+       *  @return  eof() to indicate failure, something else (usually
+       *           @a c, or not_eof())
+       *
+       *  Informally, this function is called when the output buffer is full
+       *  (or does not exist, as buffering need not actually be done).  If a
+       *  buffer exists, it is "consumed", with "some effect" on the
+       *  controlled sequence.  (Typically, the buffer is written out to the
+       *  sequence verbatim.)  In either case, the character @a c is also
+       *  written out, if @a c is not @c eof().
+       *
+       *  For a formal definiton of this function, see a good text
+       *  such as Langer & Kreft, or [27.5.2.4.5]/3-7.
+       *
+       *  A functioning output streambuf can be created by overriding only
+       *  this function (no buffer area will be used).
+       *
+       *  @note  Base class version does nothing, returns eof().
+      */
       virtual int_type 
       overflow(int_type /* __c */ = traits_type::eof())
       { return traits_type::eof(); }
 
 #ifdef _GLIBCPP_DEPRECATED
-    // http://gcc.gnu.org/ml/libstdc++/2002-05/msg00168.html
     // Annex D.6
     public:
+      /**
+       *  @brief  Tosses a character.
+       *
+       *  Advances the read pointer, ignoring the character that would have
+       *  been read.
+       *
+       *  See http://gcc.gnu.org/ml/libstdc++/2002-05/msg00168.html
+       *
+       *  @note  This function has been deprecated by the standard.  You
+       *         must define @c _GLIBCPP_DEPRECATED to make this visible; see
+       *         c++config.h.
+      */
       void 
       stossc() 
       {