2003-01-26 Jerry Quinn <jlquinn@optonline.net>

	* include/bits/codecvt.h, include/bits/locale_facets.h,
	include/bits/postypes.h, include/bits/stl_bvector.h,
	include/bits/stl_multiset.h, include/bits/stl_set.h,
	include/bits/stream_iterator.h, include/bits/streambuf_iterator.h,
	include/std/std_complex.h:  Document.


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

1 files changed, 35 insertions, 2 deletions

diff --git a/libstdc++-v3/include/bits/stream_iterator.h b/libstdc++-v3/include/bits/stream_iterator.h
index cc67505dd69..a8bc0565a90 100644
--- a/libstdc++-v3/include/bits/stream_iterator.h
+++ b/libstdc++-v3/include/bits/stream_iterator.h
@@ -1,6 +1,6 @@
 // Stream iterators
 
-// Copyright (C) 2001 Free Software Foundation, Inc.
+// Copyright (C) 2001, 2004 Free Software Foundation, Inc.
 //
 // This file is part of the GNU ISO C++ Library.  This library is free
 // software; you can redistribute it and/or modify it under the
@@ -41,6 +41,7 @@
 
 namespace std
 {
+  /// Provides input iterator semantics for streams.
   template<typename _Tp, typename _CharT = char, 
            typename _Traits = char_traits<_CharT>, typename _Dist = ptrdiff_t> 
     class istream_iterator 
@@ -56,9 +57,11 @@ namespace std
       _Tp 		_M_value;
       bool 		_M_ok;
 
-    public:      
+    public:
+      ///  Construct end of input stream iterator.
       istream_iterator() : _M_stream(0), _M_ok(false) {}
 
+      ///  Construct start of input stream iterator.
       istream_iterator(istream_type& __s) : _M_stream(&__s) { _M_read(); }
 
       istream_iterator(const istream_iterator& __obj) 
@@ -116,12 +119,14 @@ namespace std
       }
     };
   
+  ///  Return true if x and y are both end or not end, or x and y are the same.
   template<typename _Tp, typename _CharT, typename _Traits, typename _Dist>
     inline bool 
     operator==(const istream_iterator<_Tp, _CharT, _Traits, _Dist>& __x,
 	       const istream_iterator<_Tp, _CharT, _Traits, _Dist>& __y) 
     { return __x._M_equal(__y); }
 
+  ///  Return false if x and y are both end or not end, or x and y are the same.
   template <class _Tp, class _CharT, class _Traits, class _Dist>
     inline bool 
     operator!=(const istream_iterator<_Tp, _CharT, _Traits, _Dist>& __x,
@@ -129,29 +134,57 @@ namespace std
     { return !__x._M_equal(__y); }
 
 
+  /**
+   *  @brief  Provides output iterator semantics for streams.
+   *
+   *  This class provides an iterator to write to an ostream.  The type Tp is
+   *  the only type written by this iterator and there must be an
+   *  operator<<(Tp) defined.
+   *
+   *  @param  Tp  The type to write to the ostream.
+   *  @param  CharT  The ostream char_type.
+   *  @param  Traits  The ostream char_traits.
+  */
   template<typename _Tp, typename _CharT = char, 
            typename _Traits = char_traits<_CharT> >
     class ostream_iterator 
       : public iterator<output_iterator_tag, void, void, void, void>
     {
     public:
+      //@{
+      /// Public typedef
       typedef _CharT                         char_type;
       typedef _Traits                        traits_type;
       typedef basic_ostream<_CharT, _Traits> ostream_type;
+      //@}
 
     private:
       ostream_type* 	_M_stream;
       const _CharT* 	_M_string;
 
     public:
+      /// Construct from an ostream.
       ostream_iterator(ostream_type& __s) : _M_stream(&__s), _M_string(0) {}
 
+      /**
+       *  Construct from an ostream.
+       *
+       *  The delimiter string @a c is written to the stream after every Tp
+       *  written to the stream.  The delimiter is not copied, and thus must
+       *  not be destroyed while this iterator is in use.
+       *
+       *  @param  s  Underlying ostream to write to.
+       *  @param  c  CharT delimiter string to insert.
+      */
       ostream_iterator(ostream_type& __s, const _CharT* __c) 
       : _M_stream(&__s), _M_string(__c)  { }
 
+      /// Copy constructor.
       ostream_iterator(const ostream_iterator& __obj)
       : _M_stream(__obj._M_stream), _M_string(__obj._M_string)  { }
 
+      /// Writes @a value to underlying ostream using operator<<.  If
+      /// constructed with delimiter string, writes delimiter to ostream.
       ostream_iterator& 
       operator=(const _Tp& __value) 
       {