acinclude.m4: Minor comment tweaks.

2002-08-31  Phil Edwards  <pme@gcc.gnu.org>

	* acinclude.m4:  Minor comment tweaks.

	* docs/html/makedoc.awk:  New file...
	* docs/html/Makefile:  ...called from here...
	* docs/html/documentation.html:  ...to help generate this.

	* docs/html/21_strings/howto.html:  Prepare for new entry.
	* include/bits/basic_string.h:  Initial basic_stirng hook for
	doxygen.  Remove trailing whitespace.
	* include/bits/char_traits.h:  Point to onlinedocs for new entry.
	* include/bits/stringfwd.h:  Add doxygen hooks for string and
	wstring typedefs.

From-SVN: r56711

3 files changed, 260 insertions, 233 deletions

diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h
index b7d826dc08b..8f3a811f906 100644
--- a/libstdc++-v3/include/bits/basic_string.h
+++ b/libstdc++-v3/include/bits/basic_string.h
@@ -38,7 +38,7 @@
  */
 
 #ifndef _CPP_BITS_STRING_H
-#define _CPP_BITS_STRING_H	1
+#define _CPP_BITS_STRING_H        1
 
 #pragma GCC system_header
 
@@ -46,44 +46,64 @@
 
 namespace std
 {
-  // Documentation?  What's that? 
-  // Nathan Myers <ncm@cantrip.org>.
-  //
-  // A string looks like this:
-  //
-  //                               	[_Rep]
-  //                               	_M_length
-  //  [basic_string<char_type>]		_M_capacity
-  //  _M_dataplus                	_M_state
-  //  _M_p ---------------->   		unnamed array of char_type
-  
-  // Where the _M_p points to the first character in the string, and
-  // you cast it to a pointer-to-_Rep and subtract 1 to get a
-  // pointer to the header.
-  
-  // This approach has the enormous advantage that a string object
-  // requires only one allocation.  All the ugliness is confined
-  // within a single pair of inline functions, which each compile to
-  // a single "add" instruction: _Rep::_M_data(), and
-  // string::_M_rep(); and the allocation function which gets a
-  // block of raw bytes and with room enough and constructs a _Rep
-  // object at the front.
-  
-  // The reason you want _M_data pointing to the character array and
-  // not the _Rep is so that the debugger can see the string
-  // contents. (Probably we should add a non-inline member to get
-  // the _Rep for the debugger to use, so users can check the actual
-  // string length.)
-  
-  // Note that the _Rep object is a POD so that you can have a
-  // static "empty string" _Rep object already "constructed" before
-  // static constructors have run.  The reference-count encoding is
-  // chosen so that a 0 indicates one reference, so you never try to
-  // destroy the empty-string _Rep object.
-  
-  // All but the last paragraph is considered pretty conventional
-  // for a C++ string implementation.
-  
+  /**
+   *  @class basic_string basic_string.h <string>
+   *  @brief  Managing sequences of characters and character-like objects.
+   *
+   *  @ingroup Containers
+   *  @ingroup Sequences
+   *
+   *  Meets the requirements of a <a href="tables.html#65">container</a>, a
+   *  <a href="tables.html#66">reversible container</a>, and a
+   *  <a href="tables.html#67">sequence</a>.  Of the
+   *  <a href="tables.html#68">optional sequence requirements</a>, only
+   *  @c push_back, @c at, and array access are supported.
+   *
+   *  @doctodo
+   *
+   *
+   *  @if maint
+   *  Documentation?  What's that?
+   *  Nathan Myers <ncm@cantrip.org>.
+   *
+   *  A string looks like this:
+   *
+   *  @code
+   *                                        [_Rep]
+   *                                        _M_length
+   *   [basic_string<char_type>]            _M_capacity
+   *   _M_dataplus                          _M_state
+   *   _M_p ---------------->               unnamed array of char_type
+   *  @endcode
+   *
+   *  Where the _M_p points to the first character in the string, and
+   *  you cast it to a pointer-to-_Rep and subtract 1 to get a
+   *  pointer to the header.
+   *
+   *  This approach has the enormous advantage that a string object
+   *  requires only one allocation.  All the ugliness is confined
+   *  within a single pair of inline functions, which each compile to
+   *  a single "add" instruction: _Rep::_M_data(), and
+   *  string::_M_rep(); and the allocation function which gets a
+   *  block of raw bytes and with room enough and constructs a _Rep
+   *  object at the front.
+   *
+   *  The reason you want _M_data pointing to the character array and
+   *  not the _Rep is so that the debugger can see the string
+   *  contents. (Probably we should add a non-inline member to get
+   *  the _Rep for the debugger to use, so users can check the actual
+   *  string length.)
+   *
+   *  Note that the _Rep object is a POD so that you can have a
+   *  static "empty string" _Rep object already "constructed" before
+   *  static constructors have run.  The reference-count encoding is
+   *  chosen so that a 0 indicates one reference, so you never try to
+   *  destroy the empty-string _Rep object.
+   *
+   *  All but the last paragraph is considered pretty conventional
+   *  for a C++ string implementation.
+   *  @endif
+  */
   // 21.3  Template class basic_string
   template<typename _CharT, typename _Traits, typename _Alloc>
     class basic_string
@@ -104,7 +124,7 @@ namespace std
                                                             const_iterator;
       typedef reverse_iterator<const_iterator> 	const_reverse_iterator;
       typedef reverse_iterator<iterator> 		    reverse_iterator;
-    
+
     private:
       // _Rep: string representation
       //   Invariants:
@@ -125,7 +145,7 @@ namespace std
 	// Types:
 	typedef typename _Alloc::template rebind<char>::other _Raw_bytes_alloc;
 
-	// (Public) Data members: 
+	// (Public) Data members:
 
 	// The maximum number of individual char_type elements of an
 	// individual string is determined by _S_max_size. This is the
@@ -133,10 +153,10 @@ namespace std
 	// is the maximum number of bytes the allocator can allocate.)
 	// If one was to divvy up the theoretical largest size string,
 	// with a terminating character and m _CharT elements, it'd
-	// look like this: 
+	// look like this:
 	// npos = sizeof(_Rep) + (m * sizeof(_CharT)) + sizeof(_CharT)
 	// Solving for m:
-	// m = ((npos - sizeof(_Rep))/sizeof(CharT)) - 1 
+	// m = ((npos - sizeof(_Rep))/sizeof(CharT)) - 1
 	// In addition, this implementation quarters this ammount.
 	static const size_type 	_S_max_size;
 	static const _CharT 	_S_terminal;
@@ -144,7 +164,7 @@ namespace std
 	size_type 		_M_length;
 	size_type 		_M_capacity;
 	_Atomic_word		_M_references;
-	
+
         bool
 	_M_is_leaked() const
         { return _M_references < 0; }
@@ -154,50 +174,50 @@ namespace std
         { return _M_references > 0; }
 
         void
-	_M_set_leaked() 
+	_M_set_leaked()
         { _M_references = -1; }
 
         void
-	_M_set_sharable() 
+	_M_set_sharable()
         { _M_references = 0; }
 
-	_CharT* 
+	_CharT*
 	_M_refdata() throw()
 	{ return reinterpret_cast<_CharT*>(this + 1); }
 
-	_CharT& 
+	_CharT&
 	operator[](size_t __s) throw()
 	{ return _M_refdata() [__s]; }
 
-	_CharT* 
+	_CharT*
 	_M_grab(const _Alloc& __alloc1, const _Alloc& __alloc2)
-	{ 
-	  return (!_M_is_leaked() && __alloc1 == __alloc2) 
-	          ? _M_refcopy() : _M_clone(__alloc1);  
+	{
+	  return (!_M_is_leaked() && __alloc1 == __alloc2)
+	          ? _M_refcopy() : _M_clone(__alloc1);
 	}
 
 	// Create & Destroy
-	static _Rep* 
+	static _Rep*
 	_S_create(size_t, const _Alloc&);
 
-	void 
+	void
 	_M_dispose(const _Alloc& __a)
-	{ 
-	  if (__exchange_and_add(&_M_references, -1) <= 0)  
-	    _M_destroy(__a); 
+	{
+	  if (__exchange_and_add(&_M_references, -1) <= 0)
+	    _M_destroy(__a);
 	}  // XXX MT
 
-	void 
+	void
 	_M_destroy(const _Alloc&) throw();
 
-	_CharT* 
+	_CharT*
 	_M_refcopy() throw()
-	{ 
-	  __atomic_add(&_M_references, 1); 
-	  return _M_refdata(); 
+	{
+	  __atomic_add(&_M_references, 1);
+	  return _M_refdata();
 	}  // XXX MT
 
-	_CharT* 
+	_CharT*
 	_M_clone(const _Alloc&, size_type __res = 0);
       };
 
@@ -224,45 +244,45 @@ namespace std
       // (carefully) in an empty string with one reference.
       static size_type _S_empty_rep_storage[(sizeof(_Rep) + sizeof(_CharT) + sizeof(size_type) - 1)/sizeof(size_type)];
 
-      _CharT* 
-      _M_data() const 
+      _CharT*
+      _M_data() const
       { return  _M_dataplus._M_p; }
 
-      _CharT* 
-      _M_data(_CharT* __p) 
+      _CharT*
+      _M_data(_CharT* __p)
       { return (_M_dataplus._M_p = __p); }
 
-      _Rep* 
+      _Rep*
       _M_rep() const
       { return &((reinterpret_cast<_Rep*> (_M_data()))[-1]); }
 
       // For the internal use we have functions similar to `begin'/`end'
       // but they do not call _M_leak.
-      iterator 
+      iterator
       _M_ibegin() const { return iterator(_M_data()); }
 
-      iterator 
+      iterator
       _M_iend() const { return iterator(_M_data() + this->size()); }
 
-      void 
+      void
       _M_leak()    // for use in begin() & non-const op[]
-      { 
-	if (!_M_rep()->_M_is_leaked()) 
-	  _M_leak_hard(); 
+      {
+	if (!_M_rep()->_M_is_leaked())
+	  _M_leak_hard();
       }
 
-      iterator 
+      iterator
       _M_check(size_type __pos) const
-      { 
+      {
 	if (__pos > this->size())
-	  __throw_out_of_range("basic_string::_M_check"); 
-	return _M_ibegin() + __pos; 
+	  __throw_out_of_range("basic_string::_M_check");
+	return _M_ibegin() + __pos;
       }
 
       // NB: _M_fold doesn't check for a bad __pos1 value.
-      iterator 
+      iterator
       _M_fold(size_type __pos, size_type __off) const
-      { 
+      {
 	bool __testoff =  __off < this->size() - __pos;
 	size_type __newoff = __testoff ? __off : this->size() - __pos;
 	return (_M_ibegin() + __pos + __newoff);
@@ -273,8 +293,8 @@ namespace std
       template<class _Iterator>
         static void
         _S_copy_chars(_CharT* __p, _Iterator __k1, _Iterator __k2)
-        { 
-	  for (; __k1 != __k2; ++__k1, ++__p) 
+        {
+	  for (; __k1 != __k2; ++__k1, ++__p)
 	    traits_type::assign(*__p, *__k1); // These types are off.
 	}
 
@@ -285,7 +305,7 @@ namespace std
       static void
       _S_copy_chars(_CharT* __p, const_iterator __k1, const_iterator __k2)
       { _S_copy_chars(__p, __k1.base(), __k2.base()); }
- 
+
       static void
       _S_copy_chars(_CharT* __p, _CharT* __k1, _CharT* __k2)
       { traits_type::copy(__p, __k1, __k2 - __k1); }
@@ -294,13 +314,13 @@ namespace std
       _S_copy_chars(_CharT* __p, const _CharT* __k1, const _CharT* __k2)
       { traits_type::copy(__p, __k1, __k2 - __k1); }
 
-      void 
+      void
       _M_mutate(size_type __pos, size_type __len1, size_type __len2);
 
-      void 
+      void
       _M_leak_hard();
 
-      static _Rep& 
+      static _Rep&
       _S_empty_rep()
       { return *reinterpret_cast<_Rep*>(&_S_empty_rep_storage); }
 
@@ -309,10 +329,10 @@ namespace std
       // NB: We overload ctors in some cases instead of using default
       // arguments, per 17.4.4.4 para. 2 item 2.
 
-      inline 
+      inline
       basic_string();
 
-      explicit 
+      explicit
       basic_string(const _Alloc& __a);
 
       // NB: per LWG issue 42, semantics different from IS:
@@ -331,154 +351,154 @@ namespace std
         basic_string(_InputIterator __beg, _InputIterator __end,
 		     const _Alloc& __a = _Alloc());
 
-      ~basic_string() 
+      ~basic_string()
       { _M_rep()->_M_dispose(this->get_allocator()); }
 
-      basic_string& 
+      basic_string&
       operator=(const basic_string& __str) { return this->assign(__str); }
 
-      basic_string& 
+      basic_string&
       operator=(const _CharT* __s) { return this->assign(__s); }
 
-      basic_string& 
+      basic_string&
       operator=(_CharT __c) { return this->assign(1, __c); }
 
       // Iterators:
-      iterator 
-      begin() 
-      { 
-	_M_leak(); 
+      iterator
+      begin()
+      {
+	_M_leak();
 	return iterator(_M_data());
       }
 
-      const_iterator 
-      begin() const 
+      const_iterator
+      begin() const
       { return const_iterator(_M_data()); }
 
-      iterator 
+      iterator
       end()
       {
          _M_leak();
 	 return iterator(_M_data() + this->size());
       }
 
-      const_iterator 
+      const_iterator
       end() const
       { return const_iterator(_M_data() + this->size()); }
 
-      reverse_iterator 
-      rbegin() 
+      reverse_iterator
+      rbegin()
       { return reverse_iterator(this->end()); }
 
-      const_reverse_iterator 
-      rbegin() const 
+      const_reverse_iterator
+      rbegin() const
       { return const_reverse_iterator(this->end()); }
 
-      reverse_iterator 
-      rend() 
+      reverse_iterator
+      rend()
       { return reverse_iterator(this->begin()); }
 
-      const_reverse_iterator 
-      rend() const 
+      const_reverse_iterator
+      rend() const
       { return const_reverse_iterator(this->begin()); }
 
     public:
       // Capacity:
-      size_type 
+      size_type
       size() const { return _M_rep()->_M_length; }
 
-      size_type 
+      size_type
       length() const { return _M_rep()->_M_length; }
 
-      size_type 
+      size_type
       max_size() const { return _Rep::_S_max_size; }
 
-      void 
+      void
       resize(size_type __n, _CharT __c);
 
-      void 
+      void
       resize(size_type __n) { this->resize(__n, _CharT()); }
 
-      size_type 
+      size_type
       capacity() const { return _M_rep()->_M_capacity; }
 
-      void 
+      void
       reserve(size_type __res_arg = 0);
 
-      void 
+      void
       clear() { _M_mutate(0, this->size(), 0); }
 
-      bool 
+      bool
       empty() const { return this->size() == 0; }
 
       // Element access:
-      const_reference 
-      operator[] (size_type __pos) const 
+      const_reference
+      operator[] (size_type __pos) const
       { return _M_data()[__pos]; }
 
-      reference 
-      operator[](size_type __pos) 
-      { 
-	_M_leak(); 
-	return _M_data()[__pos]; 
+      reference
+      operator[](size_type __pos)
+      {
+	_M_leak();
+	return _M_data()[__pos];
       }
 
-      const_reference 
+      const_reference
       at(size_type __n) const
       {
 	if (__n >= this->size())
 	  __throw_out_of_range("basic_string::at");
-	return _M_data()[__n]; 
+	return _M_data()[__n];
       }
 
-      reference 
+      reference
       at(size_type __n)
       {
 	if (__n >= size())
 	  __throw_out_of_range("basic_string::at");
-	_M_leak(); 
-	return _M_data()[__n]; 
+	_M_leak();
+	return _M_data()[__n];
       }
 
       // Modifiers:
-      basic_string& 
+      basic_string&
       operator+=(const basic_string& __str) { return this->append(__str); }
 
-      basic_string& 
+      basic_string&
       operator+=(const _CharT* __s) { return this->append(__s); }
 
-      basic_string& 
+      basic_string&
       operator+=(_CharT __c) { return this->append(size_type(1), __c); }
 
-      basic_string& 
+      basic_string&
       append(const basic_string& __str);
 
-      basic_string& 
+      basic_string&
       append(const basic_string& __str, size_type __pos, size_type __n);
 
-      basic_string& 
+      basic_string&
       append(const _CharT* __s, size_type __n);
 
-      basic_string& 
+      basic_string&
       append(const _CharT* __s)
       { return this->append(__s, traits_type::length(__s)); }
 
-      basic_string& 
+      basic_string&
       append(size_type __n, _CharT __c);
 
       template<class _InputIterator>
-        basic_string& 
+        basic_string&
         append(_InputIterator __first, _InputIterator __last)
         { return this->replace(_M_iend(), _M_iend(), __first, __last); }
 
-      void 
+      void
       push_back(_CharT __c)
       { this->replace(_M_iend(), _M_iend(), 1, __c); }
 
-      basic_string& 
+      basic_string&
       assign(const basic_string& __str);
 
-      basic_string& 
+      basic_string&
       assign(const basic_string& __str, size_type __pos, size_type __n)
       {
 	const size_type __strsize = __str.size();
@@ -489,7 +509,7 @@ namespace std
 	return this->assign(__str._M_data() + __pos, __newsize);
       }
 
-      basic_string& 
+      basic_string&
       assign(const _CharT* __s, size_type __n)
       {
 	if (__n > this->max_size())
@@ -511,20 +531,20 @@ namespace std
 	  }
       }
 
-      basic_string& 
+      basic_string&
       assign(const _CharT* __s)
       { return this->assign(__s, traits_type::length(__s)); }
 
-      basic_string& 
+      basic_string&
       assign(size_type __n, _CharT __c)
       { return this->replace(_M_ibegin(), _M_iend(), __n, __c); }
 
       template<class _InputIterator>
-        basic_string& 
+        basic_string&
         assign(_InputIterator __first, _InputIterator __last)
         { return this->replace(_M_ibegin(), _M_iend(), __first, __last); }
 
-      void 
+      void
       insert(iterator __p, size_type __n, _CharT __c)
       {	this->replace(__p, __p, __n, __c);  }
 
@@ -532,11 +552,11 @@ namespace std
         void insert(iterator __p, _InputIterator __beg, _InputIterator __end)
         { this->replace(__p, __p, __beg, __end); }
 
-      basic_string& 
+      basic_string&
       insert(size_type __pos1, const basic_string& __str)
       { return this->insert(__pos1, __str, 0, __str.size()); }
 
-      basic_string& 
+      basic_string&
       insert(size_type __pos1, const basic_string& __str,
 	     size_type __pos2, size_type __n)
       {
@@ -545,10 +565,10 @@ namespace std
 	  __throw_out_of_range("basic_string::insert");
 	const bool __testn = __n < __strsize - __pos2;
 	const size_type __newsize = __testn ? __n : __strsize - __pos2;
-	return this->insert(__pos1, __str._M_data() + __pos2, __newsize); 
+	return this->insert(__pos1, __str._M_data() + __pos2, __newsize);
       }
 
-      basic_string& 
+      basic_string&
       insert(size_type __pos, const _CharT* __s, size_type __n)
       {
 	const size_type __size = this->size();
@@ -582,43 +602,43 @@ namespace std
 	  }
        }
 
-      basic_string&  
+      basic_string&
       insert(size_type __pos, const _CharT* __s)
       { return this->insert(__pos, __s, traits_type::length(__s)); }
 
-      basic_string& 
+      basic_string&
       insert(size_type __pos, size_type __n, _CharT __c)
-      { 
-	this->insert(_M_check(__pos), __n, __c); 
-	return *this; 
+      {
+	this->insert(_M_check(__pos), __n, __c);
+	return *this;
       }
 
-      iterator 
+      iterator
       insert(iterator __p, _CharT __c = _CharT())
       {
 	size_type __pos = __p - _M_ibegin();
 	this->insert(_M_check(__pos), size_type(1), __c);
-	_M_rep()->_M_set_leaked(); 
- 	return this->_M_ibegin() + __pos; 
+	_M_rep()->_M_set_leaked();
+ 	return this->_M_ibegin() + __pos;
       }
 
-      basic_string& 
+      basic_string&
       erase(size_type __pos = 0, size_type __n = npos)
-      { 
+      {
 	return this->replace(_M_check(__pos), _M_fold(__pos, __n),
-			     _M_data(), _M_data()); 
+			     _M_data(), _M_data());
       }
 
-      iterator 
+      iterator
       erase(iterator __position)
       {
 	size_type __i = __position - _M_ibegin();
         this->replace(__position, __position + 1, _M_data(), _M_data());
-	_M_rep()->_M_set_leaked(); 
+	_M_rep()->_M_set_leaked();
 	return _M_ibegin() + __i;
       }
 
-      iterator 
+      iterator
       erase(iterator __first, iterator __last)
       {
         size_type __i = __first - _M_ibegin();
@@ -627,18 +647,18 @@ namespace std
        return _M_ibegin() + __i;
       }
 
-      basic_string& 
+      basic_string&
       replace(size_type __pos, size_type __n, const basic_string& __str)
       { return this->replace(__pos, __n, __str._M_data(), __str.size()); }
 
-      basic_string& 
+      basic_string&
       replace(size_type __pos1, size_type __n1, const basic_string& __str,
 	      size_type __pos2, size_type __n2);
 
-      basic_string& 
+      basic_string&
       replace(size_type __pos, size_type __n1, const _CharT* __s,
 	      size_type __n2)
-      { 
+      {
 	const size_type __size = this->size();
  	if (__pos > __size)
 	  __throw_out_of_range("basic_string::replace");
@@ -657,32 +677,32 @@ namespace std
 			  typename iterator_traits<const _CharT*>::iterator_category());
       }
 
-      basic_string& 
+      basic_string&
       replace(size_type __pos, size_type __n1, const _CharT* __s)
       { return this->replace(__pos, __n1, __s, traits_type::length(__s)); }
 
-      basic_string& 
+      basic_string&
       replace(size_type __pos, size_type __n1, size_type __n2, _CharT __c)
       { return this->replace(_M_check(__pos), _M_fold(__pos, __n1), __n2, __c); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, const basic_string& __str)
       { return this->replace(__i1, __i2, __str._M_data(), __str.size()); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2,
                            const _CharT* __s, size_type __n)
       { return this->replace(__i1 - _M_ibegin(), __i2 - __i1, __s, __n); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, const _CharT* __s)
       { return this->replace(__i1, __i2, __s, traits_type::length(__s)); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, size_type __n, _CharT __c);
 
       template<class _InputIterator>
-        basic_string& 
+        basic_string&
         replace(iterator __i1, iterator __i2,
 		_InputIterator __k1, _InputIterator __k2)
         { return _M_replace(__i1, __i2, __k1, __k2,
@@ -690,23 +710,23 @@ namespace std
 
       // Specializations for the common case of pointer and iterator:
       // useful to avoid the overhead of temporary buffering in _M_replace.
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, _CharT* __k1, _CharT* __k2)
         { return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
 			       __k1, __k2 - __k1); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, const _CharT* __k1, const _CharT* __k2)
         { return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
 			       __k1, __k2 - __k1); }
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, iterator __k1, iterator __k2)
         { return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
 			       __k1.base(), __k2 - __k1);
 	}
 
-      basic_string& 
+      basic_string&
       replace(iterator __i1, iterator __i2, const_iterator __k1, const_iterator __k2)
         { return this->replace(__i1 - _M_ibegin(), __i2 - __i1,
 			       __k1.base(), __k2 - __k1);
@@ -714,13 +734,13 @@ namespace std
 
     private:
       template<class _InputIterator>
-        basic_string& 
-        _M_replace(iterator __i1, iterator __i2, _InputIterator __k1, 
+        basic_string&
+        _M_replace(iterator __i1, iterator __i2, _InputIterator __k1,
 		   _InputIterator __k2, input_iterator_tag);
 
       template<class _ForwardIterator>
-        basic_string& 
-        _M_replace_safe(iterator __i1, iterator __i2, _ForwardIterator __k1, 
+        basic_string&
+        _M_replace_safe(iterator __i1, iterator __i2, _ForwardIterator __k1,
 		   _ForwardIterator __k2);
 
       // _S_construct_aux is used to implement the 21.3.1 para 15 which
@@ -733,7 +753,7 @@ namespace std
           typedef typename iterator_traits<_InIter>::iterator_category _Tag;
           return _S_construct(__beg, __end, __a, _Tag());
 	}
- 
+
       template<class _InIter>
         static _CharT*
         _S_construct_aux(_InIter __beg, _InIter __end, const _Alloc& __a,
@@ -742,7 +762,7 @@ namespace std
 	  return _S_construct(static_cast<size_type>(__beg),
 			      static_cast<value_type>(__end), __a);
 	}
- 
+
       template<class _InIter>
         static _CharT*
         _S_construct(_InIter __beg, _InIter __end, const _Alloc& __a)
@@ -756,7 +776,7 @@ namespace std
         static _CharT*
          _S_construct(_InIter __beg, _InIter __end, const _Alloc& __a,
 		      input_iterator_tag);
-      
+
       // For forward_iterators up to random_access_iterators, used for
       // string::iterator, _CharT*, etc.
       template<class _FwdIter>
@@ -764,19 +784,19 @@ namespace std
         _S_construct(_FwdIter __beg, _FwdIter __end, const _Alloc& __a,
 		     forward_iterator_tag);
 
-      static _CharT* 
+      static _CharT*
       _S_construct(size_type __req, _CharT __c, const _Alloc& __a);
 
     public:
 
-      size_type 
+      size_type
       copy(_CharT* __s, size_type __n, size_type __pos = 0) const;
 
-      void 
+      void
       swap(basic_string<_CharT, _Traits, _Alloc>& __s);
 
       // String operations:
-      const _CharT* 
+      const _CharT*
       c_str() const
       {
 	// MT: This assumes concurrent writes are OK.
@@ -785,137 +805,137 @@ namespace std
         return _M_data();
       }
 
-      const _CharT* 
+      const _CharT*
       data() const { return _M_data(); }
 
-      allocator_type 
+      allocator_type
       get_allocator() const { return _M_dataplus; }
 
-      size_type 
+      size_type
       find(const _CharT* __s, size_type __pos, size_type __n) const;
 
-      size_type 
+      size_type
       find(const basic_string& __str, size_type __pos = 0) const
       { return this->find(__str.data(), __pos, __str.size()); }
 
-      size_type 
+      size_type
       find(const _CharT* __s, size_type __pos = 0) const
       { return this->find(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       find(_CharT __c, size_type __pos = 0) const;
 
-      size_type 
+      size_type
       rfind(const basic_string& __str, size_type __pos = npos) const
       { return this->rfind(__str.data(), __pos, __str.size()); }
 
-      size_type 
+      size_type
       rfind(const _CharT* __s, size_type __pos, size_type __n) const;
 
-      size_type 
+      size_type
       rfind(const _CharT* __s, size_type __pos = npos) const
       { return this->rfind(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       rfind(_CharT __c, size_type __pos = npos) const;
 
-      size_type 
+      size_type
       find_first_of(const basic_string& __str, size_type __pos = 0) const
       { return this->find_first_of(__str.data(), __pos, __str.size()); }
 
-      size_type 
+      size_type
       find_first_of(const _CharT* __s, size_type __pos, size_type __n) const;
 
-      size_type 
+      size_type
       find_first_of(const _CharT* __s, size_type __pos = 0) const
       { return this->find_first_of(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       find_first_of(_CharT __c, size_type __pos = 0) const
       { return this->find(__c, __pos); }
 
-      size_type 
+      size_type
       find_last_of(const basic_string& __str, size_type __pos = npos) const
       { return this->find_last_of(__str.data(), __pos, __str.size()); }
 
-      size_type 
+      size_type
       find_last_of(const _CharT* __s, size_type __pos, size_type __n) const;
 
-      size_type 
+      size_type
       find_last_of(const _CharT* __s, size_type __pos = npos) const
       { return this->find_last_of(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       find_last_of(_CharT __c, size_type __pos = npos) const
       { return this->rfind(__c, __pos); }
 
-      size_type 
+      size_type
       find_first_not_of(const basic_string& __str, size_type __pos = 0) const
       { return this->find_first_not_of(__str.data(), __pos, __str.size()); }
 
-      size_type 
-      find_first_not_of(const _CharT* __s, size_type __pos, 
+      size_type
+      find_first_not_of(const _CharT* __s, size_type __pos,
 			size_type __n) const;
 
-      size_type 
+      size_type
       find_first_not_of(const _CharT* __s, size_type __pos = 0) const
       { return this->find_first_not_of(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       find_first_not_of(_CharT __c, size_type __pos = 0) const;
 
-      size_type 
+      size_type
       find_last_not_of(const basic_string& __str, size_type __pos = npos) const
       { return this->find_last_not_of(__str.data(), __pos, __str.size()); }
 
-      size_type 
-      find_last_not_of(const _CharT* __s, size_type __pos, 
+      size_type
+      find_last_not_of(const _CharT* __s, size_type __pos,
 		       size_type __n) const;
-      size_type 
+      size_type
       find_last_not_of(const _CharT* __s, size_type __pos = npos) const
       { return this->find_last_not_of(__s, __pos, traits_type::length(__s)); }
 
-      size_type 
+      size_type
       find_last_not_of(_CharT __c, size_type __pos = npos) const;
 
-      basic_string 
+      basic_string
       substr(size_type __pos = 0, size_type __n = npos) const
-      { 
+      {
 	if (__pos > this->size())
 	  __throw_out_of_range("basic_string::substr");
-	return basic_string(*this, __pos, __n); 
+	return basic_string(*this, __pos, __n);
       }
 
-      int 
+      int
       compare(const basic_string& __str) const
       {
 	size_type __size = this->size();
 	size_type __osize = __str.size();
 	size_type __len = min(__size, __osize);
-      
+
 	int __r = traits_type::compare(_M_data(), __str.data(), __len);
 	if (!__r)
 	  __r =  __size - __osize;
 	return __r;
       }
 
-      int 
+      int
       compare(size_type __pos, size_type __n, const basic_string& __str) const;
 
-      int 
+      int
       compare(size_type __pos1, size_type __n1, const basic_string& __str,
 	      size_type __pos2, size_type __n2) const;
 
-      int 
+      int
       compare(const _CharT* __s) const;
 
       // _GLIBCPP_RESOLVE_LIB_DEFECTS
       // 5. String::compare specification questionable
-      int 
+      int
       compare(size_type __pos, size_type __n1, const _CharT* __s) const;
 
-      int 
-      compare(size_type __pos, size_type __n1, const _CharT* __s, 
+      int
+      compare(size_type __pos, size_type __n1, const _CharT* __s,
 	      size_type __n2) const;
   };
 
diff --git a/libstdc++-v3/include/bits/char_traits.h b/libstdc++-v3/include/bits/char_traits.h
index a5fdfbef296..2b733cd94a0 100644
--- a/libstdc++-v3/include/bits/char_traits.h
+++ b/libstdc++-v3/include/bits/char_traits.h
@@ -42,17 +42,21 @@
 
 #pragma GCC system_header
 
-#include <cstring> 	// For memmove, memset, memchr
-#include <bits/fpos.h> 		// For streampos
+#include <cstring>            // For memmove, memset, memchr
+#include <bits/fpos.h>        // For streampos
 
 namespace std 
 {
-  // 21.1.2
+  // 21.1
   /**
    *  @brief  Basis for explicit traits specializations.
    *
    *  @note  For any given actual character type, this definition is
    *  probably wrong.
+   *
+   *  See http://gcc.gnu.org/onlinedocs/libstdc++/21_strings/howto.html#5
+   *  for advice on how to make use of this class for "unusual" character
+   *  types.
   */
   template<class _CharT>
     struct char_traits
@@ -108,7 +112,7 @@ namespace std
     };
 
 
-  /// 21.1.4  char_traits specializations
+  /// 21.1.3.1  char_traits specializations
   template<>
     struct char_traits<char>
     {
@@ -178,6 +182,7 @@ namespace std
 
 
 #ifdef _GLIBCPP_USE_WCHAR_T
+  /// 21.1.3.2  char_traits specializations
   template<>
     struct char_traits<wchar_t>
     {
diff --git a/libstdc++-v3/include/bits/stringfwd.h b/libstdc++-v3/include/bits/stringfwd.h
index b7418a67a7e..07b1009a4b2 100644
--- a/libstdc++-v3/include/bits/stringfwd.h
+++ b/libstdc++-v3/include/bits/stringfwd.h
@@ -60,7 +60,9 @@ namespace std
            typename _Alloc = allocator<_CharT> >
     class basic_string;
 
+  /// 99%% of %string users only ever [need to] see the typedef.
   typedef basic_string<char>    string;
+  /// 99%% of %wstring users only ever [need to] see the typedef.
   typedef basic_string<wchar_t> wstring;
 } // namespace std