TODO: Note change in clause 27 docs.

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.

From-SVN: r59325

libstdc++-v3/ChangeLog

+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.
+
 2002-11-20  Benjamin Kosnik  <bkoz@redhat.com>
             Jonathan Lennox  <lennox@cs.columbia.edu>
 

libstdc++-v3/docs/doxygen/TODO

@@ -31,7 +31,11 @@ c24             stl_iterator.h (__normal_iterator, other small TODO bits)
                 stream iterators
 c25             stl_algo.h (lots of stuff)
 c26             <complex>, <valarray>, stl_numeric.h[26.4], Note A
-c27             Untouched
+c27             ios_base callbacks and local storage
+                basic_ios::copyfmt()
+                std_streambuf.h's __copy_streambufs()
+                    " "           _M_* protected memfns (data has been done)
+                fstream and sstream protected members
 
 backward/*      Not scanned by doxygen.  Should it be?  Doubtful.
 

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

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);
-    /** @} */
+    //@}
   };
   
   

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

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)
   { 

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

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;