locale_facets.h: Document public classes and functions.

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

	* include/bits/locale_facets.h: Document public classes and
	functions.
	* include/bits/locale_facets.tcc (time_get::_M_extract_via_format):
	Add comment.

From-SVN: r75498

3 files changed, 1440 insertions, 6 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 34829ad..3902d54 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,10 @@
+2003-01-06  Jerry Quinn  <jlquinn@optonline.net>
+
+	* include/bits/locale_facets.h: Document public classes and
+	functions.
+	* include/bits/locale_facets.tcc (time_get::_M_extract_via_format):
+	Add comment.
+
 2004-01-06  Paolo Carlini  <pcarlini@suse.de>
 
 	* testsuite/27_io/basic_istream/extractors_other/char/1.cc:
diff --git a/libstdc++-v3/include/bits/locale_facets.h b/libstdc++-v3/include/bits/locale_facets.h
index bf64278..2926573 100644
--- a/libstdc++-v3/include/bits/locale_facets.h
+++ b/libstdc++-v3/include/bits/locale_facets.h
@@ -1683,76 +1683,221 @@ namespace std
 	}
     }
 
+  /**
+   *  @brief  Numpunct facet.
+   *
+   *  This facet stores several pieces of information related to printing and
+   *  scanning numbers, such as the decimal point character.  It takes a
+   *  template parameter specifying the char type.  The numpunct facet is
+   *  used by streams for many I/O operations involving numbers.
+   *
+   *  The numpunct template uses protected virtual functions to provide the
+   *  actual results.  The public accessors forward the call to the virtual
+   *  functions.  These virtual functions are hooks for developers to
+   *  implement the behavior they require from a numpunct facet.
+  */
   template<typename _CharT>
     class numpunct : public locale::facet
     {
     public:
       // Types:
+      //@{
+      /// Public typedefs
       typedef _CharT          		char_type;
       typedef basic_string<_CharT> 	string_type;
+      //@}
       typedef __numpunct_cache<_CharT>  __cache_type;
 
     protected:
       __cache_type*			_M_data;
 
     public:
+      /// Numpunct facet id.
       static locale::id 		id;
 
+      /**
+       *  @brief  Numpunct constructor.
+       *
+       *  @param  refs  Refcount to pass to the base class.
+       */
       explicit 
       numpunct(size_t __refs = 0) : facet(__refs), _M_data(NULL)
       { _M_initialize_numpunct(); }
 
+      /**
+       *  @brief  Internal constructor.  Not for general use.
+       *
+       *  This is a constructor for use by the library itself to set up the
+       *  predefined locale facets.
+       *
+       *  @param  cache  __numpunct_cache object.
+       *  @param  refs  Refcount to pass to the base class.
+       */
       explicit 
       numpunct(__cache_type* __cache, size_t __refs = 0) 
       : facet(__refs), _M_data(__cache)
       { _M_initialize_numpunct(); }
 
+      /**
+       *  @brief  Internal constructor.  Not for general use.
+       *
+       *  This is a constructor for use by the library itself to set up new
+       *  locales.
+       *
+       *  @param  cloc  The "C" locale.
+       *  @param  refs  Refcount to pass to the base class.
+       */
       explicit 
       numpunct(__c_locale __cloc, size_t __refs = 0) 
       : facet(__refs), _M_data(NULL)
       { _M_initialize_numpunct(__cloc); }
 
+      /**
+       *  @brief  Return decimal point character.
+       *
+       *  This function returns a char_type to use as a decimal point.  It
+       *  does so by returning returning
+       *  numpunct<char_type>::do_decimal_point().
+       *
+       *  @return  @a char_type representing a decimal point.
+      */
       char_type    
       decimal_point() const
       { return this->do_decimal_point(); }
 
+      /**
+       *  @brief  Return thousands separator character.
+       *
+       *  This function returns a char_type to use as a thousands separator.  It
+       *  does so by returning returning
+       *  numpunct<char_type>::do_thousands_sep().
+       *
+       *  @return  char_type representing a thousands separator.
+      */
       char_type    
       thousands_sep() const
       { return this->do_thousands_sep(); }
 
+      /**
+       *  @brief  Return grouping specification.
+       *
+       *  This function returns a string representing groupings for the
+       *  integer part of a number.  Groupings indicate where thousands
+       *  separators should be inserted in the integer part of a number.
+       *
+       *  Each char in the return string is interpret as an integer rather
+       *  than a character.  These numbers represent the number of digits in a
+       *  group.  The first char in the string represents the number of digits
+       *  in the least significant group.  If a char is negative, it indicates
+       *  an unlimited number of digits for the group.  If more chars from the
+       *  string are required to group a number, the last char is used
+       *  repeatedly.
+       *
+       *  For example, if the grouping() returns "\003\002" and is applied to
+       *  the number 123456789, this corresponds to 12,34,56,789.  Note that
+       *  if the string was "32", this would put more than 50 digits into the
+       *  least significant group if the character set is ASCII.
+       *
+       *  The string is returned by calling
+       *  numpunct<char_type>::do_grouping().
+       *
+       *  @return  string representing grouping specification.
+      */
       string       
       grouping() const
       { return this->do_grouping(); }
 
+      /**
+       *  @brief  Return string representation of bool true.
+       *
+       *  This function returns a string_type containing the text
+       *  representation for true bool variables.  It does so by calling
+       *  numpunct<char_type>::do_truename().
+       *
+       *  @return  string_type representing printed form of true.
+      */
       string_type  
       truename() const
       { return this->do_truename(); }
 
+      /**
+       *  @brief  Return string representation of bool false.
+       *
+       *  This function returns a string_type containing the text
+       *  representation for false bool variables.  It does so by calling
+       *  numpunct<char_type>::do_falsename().
+       *
+       *  @return  string_type representing printed form of false.
+      */
       string_type  
       falsename() const
       { return this->do_falsename(); }
 
     protected:
+      /// Destructor.
       virtual 
       ~numpunct();
 
+      /**
+       *  @brief  Return decimal point character.
+       *
+       *  Returns a char_type to use as a decimal point.  This function is a
+       *  hook for derived classes to change the value returned.
+       *
+       *  @return  @a char_type representing a decimal point.
+      */
       virtual char_type    
       do_decimal_point() const
       { return _M_data->_M_decimal_point; }
 
+      /**
+       *  @brief  Return thousands separator character.
+       *
+       *  Returns a char_type to use as a thousands separator.  This function
+       *  is a hook for derived classes to change the value returned.
+       *
+       *  @return  @a char_type representing a thousands separator.
+      */
       virtual char_type    
       do_thousands_sep() const
       { return _M_data->_M_thousands_sep; }
 
+      /**
+       *  @brief  Return grouping specification.
+       *
+       *  Returns a string representing groupings for the integer part of a
+       *  number.  This function is a hook for derived classes to change the
+       *  value returned.  @see grouping() for details.
+       *
+       *  @return  String representing grouping specification.
+      */
       virtual string
       do_grouping() const
       { return _M_data->_M_grouping; }
 
-      virtual string_type  
+      /**
+       *  @brief  Return string representation of bool true.
+       *
+       *  Returns a string_type containing the text representation for true
+       *  bool variables.  This function is a hook for derived classes to
+       *  change the value returned.
+       *
+       *  @return  string_type representing printed form of true.
+      */
+      virtual string_type
       do_truename() const
       { return _M_data->_M_truename; }
 
-      virtual string_type  
+      /**
+       *  @brief  Return string representation of bool false.
+       *
+       *  Returns a string_type containing the text representation for false
+       *  bool variables.  This function is a hook for derived classes to
+       *  change the value returned.
+       *
+       *  @return  string_type representing printed form of false.
+      */
+      virtual string_type
       do_falsename() const
       { return _M_data->_M_falsename; }
 
@@ -1805,24 +1950,100 @@ namespace std
       ~numpunct_byname() { }	
     };
 
+  /**
+   *  @brief  Facet for parsing number strings.
+   *
+   *  This facet encapsulates the code to parse and return a number
+   *  from a string.  It is used by the istream numeric extraction
+   *  operators.
+   *
+   *  The num_get template uses protected virtual functions to provide the
+   *  actual results.  The public accessors forward the call to the virtual
+   *  functions.  These virtual functions are hooks for developers to
+   *  implement the behavior they require from the num_get facet.
+  */
   template<typename _CharT, typename _InIter>
     class num_get : public locale::facet, public __num_base
     {
     public:
       // Types:
+      //@{
+      /// Public typedefs
       typedef _CharT   			char_type;
       typedef _InIter  			iter_type;
+      //@}
 
+      /// Numpunct facet id.
       static locale::id 		id;
 
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  This is the constructor provided by the standard.
+       *
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       num_get(size_t __refs = 0) : facet(__refs) { }
 
+      /**
+       *  @brief  Numeric parsing.
+       *
+       *  Parses the input stream into the bool @a v.  It does so by calling
+       *  num_put::do_put().
+       *
+       *  If ios_base::boolalpha is set, attempts to read ctype<CharT>::truename() or
+       *  ctype<CharT>::falsename().  Sets @a v to true or false if
+       *  successful.  Sets err to ios_base::failbit if reading the string
+       *  fails.  Sets err to ios_base::eofbit if the stream is emptied.
+       *
+       *  If ios_base::boolalpha is not set, proceeds as with reading a long,
+       *  except if the value is 1, sets @a v to true, if the value is 0, sets
+       *  @a v to false, and otherwise set err to ios_base::failbit.
+       *
+       *  @param  in  Start of input stream.
+       *  @param  end  End of input stream.
+       *  @param  io  Source of locale and flags.
+       *  @param  err  Error flags to set.
+       *  @param  v  Value to format and insert.
+       *  @return  Iterator after reading.
+      */
       iter_type 
       get(iter_type __in, iter_type __end, ios_base& __io,
 	  ios_base::iostate& __err, bool& __v) const
       { return this->do_get(__in, __end, __io, __err, __v); }
 
+      //@{
+      /**
+       *  @brief  Numeric parsing.
+       *
+       *  Parses the input stream into the integral variable @a v.  It does so
+       *  by calling num_put::do_put().
+       *
+       *  Parsing is affected by the flag settings in @a io.
+       *
+       *  The basic parse is affected by the value of io.flags() &
+       *  ios_base::basefield.  If equal to ios_base::oct, parses like the
+       *  scanf %o specifier.  Else if equal to ios_base::hex, parses like %X
+       *  specifier.  Else if basefield equal to 0, parses like the %i
+       *  specifier.  Otherwise, parses like %d for signed and %u for unsigned
+       *  types.  The matching type length modifier is also used.
+       *
+       *  Digit grouping is intrepreted according to numpunct::grouping() and
+       *  numpunct::thousands_sep().  If the pattern of digit groups isn't
+       *  consistent, sets err to ios_base::failbit.
+       *
+       *  If parsing the string yields a valid value for @a v, @a v is set.
+       *  Otherwise, sets err to ios_base::failbit and leaves @a v unaltered.
+       *  Sets err to ios_base::eofbit if the stream is emptied.
+       *
+       *  @param  in  Start of input stream.
+       *  @param  end  End of input stream.
+       *  @param  io  Source of locale and flags.
+       *  @param  err  Error flags to set.
+       *  @param  v  Value to format and insert.
+       *  @return  Iterator after reading.
+      */
       iter_type
       get(iter_type __in, iter_type __end, ios_base& __io, 
 	  ios_base::iostate& __err, long& __v) const
@@ -1854,7 +2075,34 @@ namespace std
 	  ios_base::iostate& __err, unsigned long long& __v)  const
       { return this->do_get(__in, __end, __io, __err, __v); }
 #endif
+      //@}
 
+      //@{
+      /**
+       *  @brief  Numeric parsing.
+       *
+       *  Parses the input stream into the integral variable @a v.  It does so
+       *  by calling num_put::do_put().
+       *
+       *  The input characters are parsed like the scanf %g specifier.  The
+       *  matching type length modifier is also used.
+       *
+       *  The decimal point character used is numpunct::decimal_point().
+       *  Digit grouping is intrepreted according to numpunct::grouping() and
+       *  numpunct::thousands_sep().  If the pattern of digit groups isn't
+       *  consistent, sets err to ios_base::failbit.
+       *
+       *  If parsing the string yields a valid value for @a v, @a v is set.
+       *  Otherwise, sets err to ios_base::failbit and leaves @a v unaltered.
+       *  Sets err to ios_base::eofbit if the stream is emptied.
+       *
+       *  @param  in  Start of input stream.
+       *  @param  end  End of input stream.
+       *  @param  io  Source of locale and flags.
+       *  @param  err  Error flags to set.
+       *  @param  v  Value to format and insert.
+       *  @return  Iterator after reading.
+      */
       iter_type 
       get(iter_type __in, iter_type __end, ios_base& __io,
 	  ios_base::iostate& __err, float& __v) const
@@ -1869,13 +2117,41 @@ namespace std
       get(iter_type __in, iter_type __end, ios_base& __io,
 	  ios_base::iostate& __err, long double& __v) const
       { return this->do_get(__in, __end, __io, __err, __v); }
+      //@}
 
+      /**
+       *  @brief  Numeric parsing.
+       *
+       *  Parses the input stream into the pointer variable @a v.  It does so
+       *  by calling num_put::do_put().
+       *
+       *  The input characters are parsed like the scanf %p specifier.
+       *
+       *  Digit grouping is intrepreted according to numpunct::grouping() and
+       *  numpunct::thousands_sep().  If the pattern of digit groups isn't
+       *  consistent, sets err to ios_base::failbit.
+       *
+       *  Note that the digit grouping effect for pointers is a bit ambiguous
+       *  in the standard and shouldn't be relied on.  See DR 344.
+       *
+       *  If parsing the string yields a valid value for @a v, @a v is set.
+       *  Otherwise, sets err to ios_base::failbit and leaves @a v unaltered.
+       *  Sets err to ios_base::eofbit if the stream is emptied.
+       *
+       *  @param  in  Start of input stream.
+       *  @param  end  End of input stream.
+       *  @param  io  Source of locale and flags.
+       *  @param  err  Error flags to set.
+       *  @param  v  Value to format and insert.
+       *  @return  Iterator after reading.
+      */
       iter_type 
       get(iter_type __in, iter_type __end, ios_base& __io,
 	  ios_base::iostate& __err, void*& __v) const
       { return this->do_get(__in, __end, __io, __err, __v); }      
 
     protected:
+      /// Destructor.
       virtual ~num_get() { }
 
       iter_type 
@@ -1887,6 +2163,21 @@ namespace std
         _M_extract_int(iter_type, iter_type, ios_base&, ios_base::iostate&, 
 		       _ValueT& __v) const;
 
+      //@{
+      /**
+       *  @brief  Numeric parsing.
+       *
+       *  Parses the input stream into the variable @a v.  This function is a
+       *  hook for derived classes to change the value returned.  @see get()
+       *  for more details.
+       *
+       *  @param  in  Start of input stream.
+       *  @param  end  End of input stream.
+       *  @param  io  Source of locale and flags.
+       *  @param  err  Error flags to set.
+       *  @param  v  Value to format and insert.
+       *  @return  Iterator after reading.
+      */
       virtual iter_type 
       do_get(iter_type, iter_type, ios_base&, ios_base::iostate&, bool&) const;
 
@@ -1931,28 +2222,105 @@ namespace std
       virtual iter_type 
       do_get(iter_type, iter_type, ios_base&, ios_base::iostate& __err, 
 	     void*&) const;
+      //@}
     };
 
   template<typename _CharT, typename _InIter>
     locale::id num_get<_CharT, _InIter>::id;
 
 
+  /**
+   *  @brief  Facet for converting numbers to strings.
+   *
+   *  This facet encapsulates the code to convert a number to a string.  It is
+   *  used by the ostream numeric insertion operators.
+   *
+   *  The num_put template uses protected virtual functions to provide the
+   *  actual results.  The public accessors forward the call to the virtual
+   *  functions.  These virtual functions are hooks for developers to
+   *  implement the behavior they require from the num_put facet.
+  */
   template<typename _CharT, typename _OutIter>
     class num_put : public locale::facet, public __num_base
     {
     public:
       // Types:
+      //@{
+      /// Public typedefs
       typedef _CharT       	char_type;
       typedef _OutIter     	iter_type;
+      //@}
+
+      /// Numpunct facet id.
       static locale::id		id;
 
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  This is the constructor provided by the standard.
+       *
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       num_put(size_t __refs = 0) : facet(__refs) { }
 
+      /**
+       *  @brief  Numeric formatting.
+       *
+       *  Formats the boolean @a v and inserts it into a stream.  It does so
+       *  by calling num_put::do_put().
+       *
+       *  If ios_base::boolalpha is set, writes ctype<CharT>::truename() or
+       *  ctype<CharT>::falsename().  Otherwise formats @a v as an int.
+       *
+       *  @param  s  Stream to write to.
+       *  @param  io  Source of locale and flags.
+       *  @param  fill  Char_type to use for filling.
+       *  @param  v  Value to format and insert.
+       *  @return  Iterator after writing.
+      */
       iter_type 
       put(iter_type __s, ios_base& __f, char_type __fill, bool __v) const
       { return this->do_put(__s, __f, __fill, __v); }
 
+      //@{
+      /**
+       *  @brief  Numeric formatting.
+       *
+       *  Formats the integral value @a v and inserts it into a stream.  It does so
+       *  by calling num_put::do_put().
+       *
+       *  Formatting is affected by the flag settings in @a io.
+       *
+       *  The basic format is affected by the value of io.flags() &
+       *  ios_base::basefield.  If equal to ios_base::oct, formats like the
+       *  printf %o specifier.  Else if equal to ios_base::hex, formats like
+       *  %x or %X with ios_base::uppercase unset or set respectively.
+       *  Otherwise, formats like %d, %ld, %lld for signed and %u, %lu, %llu
+       *  for unsigned values.  Note that if both oct and hex are set, neither
+       *  will take effect.
+       *
+       *  If ios_base::showpos is set, '+' is output before positive values.
+       *  If ios_base::showbase is set, '0' precedes octal values (except 0)
+       *  and '0[xX]' precedes hex values.
+       *
+       *  Thousands separators are inserted according to numpunct::grouping()
+       *  and numpunct::thousands_sep().  The decimal point character used is
+       *  numpunct::decimal_point().
+       *
+       *  If io.width() is non-zero, enough @a fill characters are inserted to
+       *  make the result at least that wide.  If
+       *  (io.flags() & ios_base::adjustfield) == ios_base::left, result is
+       *  padded at the end.  If ios_base::internal, then padding occurs
+       *  immediately after either a '+' or '-' or after '0x' or '0X'.
+       *  Otherwise, padding occurs at the beginning.
+       *
+       *  @param  s  Stream to write to.
+       *  @param  io  Source of locale and flags.
+       *  @param  fill  Char_type to use for filling.
+       *  @param  v  Value to format and insert.
+       *  @return  Iterator after writing.
+      */
       iter_type 
       put(iter_type __s, ios_base& __f, char_type __fill, long __v) const
       { return this->do_put(__s, __f, __fill, __v); }
@@ -1972,7 +2340,50 @@ namespace std
 	  unsigned long long __v) const
       { return this->do_put(__s, __f, __fill, __v); }
 #endif
+      //@}
 
+      //@{
+      /**
+       *  @brief  Numeric formatting.
+       *
+       *  Formats the floating point value @a v and inserts it into a stream.
+       *  It does so by calling num_put::do_put().
+       *
+       *  Formatting is affected by the flag settings in @a io.
+       *
+       *  The basic format is affected by the value of io.flags() &
+       *  ios_base::floatfield.  If equal to ios_base::fixed, formats like the
+       *  printf %f specifier.  Else if equal to ios_base::scientific, formats
+       *  like %e or %E with ios_base::uppercase unset or set respectively.
+       *  Otherwise, formats like %g or %G depending on uppercase.  Note that
+       *  if both fixed and scientific are set, the effect will also be like
+       *  %g or %G.
+       *
+       *  The output precision is given by io.precision().  This precision is
+       *  capped at numeric_limits::digits10 + 2 (different for double and
+       *  long double).  The default precision is 6.
+       *
+       *  If ios_base::showpos is set, '+' is output before positive values.
+       *  If ios_base::showpoint is set, a decimal point will always be
+       *  output.
+       *
+       *  Thousands separators are inserted according to numpunct::grouping()
+       *  and numpunct::thousands_sep().  The decimal point character used is
+       *  numpunct::decimal_point().
+       *
+       *  If io.width() is non-zero, enough @a fill characters are inserted to
+       *  make the result at least that wide.  If
+       *  (io.flags() & ios_base::adjustfield) == ios_base::left, result is
+       *  padded at the end.  If ios_base::internal, then padding occurs
+       *  immediately after either a '+' or '-' or after '0x' or '0X'.
+       *  Otherwise, padding occurs at the beginning.
+       *
+       *  @param  s  Stream to write to.
+       *  @param  io  Source of locale and flags.
+       *  @param  fill  Char_type to use for filling.
+       *  @param  v  Value to format and insert.
+       *  @return  Iterator after writing.
+      */
       iter_type 
       put(iter_type __s, ios_base& __f, char_type __fill, double __v) const
       { return this->do_put(__s, __f, __fill, __v); }
@@ -1981,7 +2392,23 @@ namespace std
       put(iter_type __s, ios_base& __f, char_type __fill, 
 	  long double __v) const
       { return this->do_put(__s, __f, __fill, __v); }
+      //@}
 
+      /**
+       *  @brief  Numeric formatting.
+       *
+       *  Formats the pointer value @a v and inserts it into a stream.  It
+       *  does so by calling num_put::do_put().
+       *
+       *  This function formats @a v as an unsigned long with ios_base::hex
+       *  and ios_base::showbase set.
+       *
+       *  @param  s  Stream to write to.
+       *  @param  io  Source of locale and flags.
+       *  @param  fill  Char_type to use for filling.
+       *  @param  v  Value to format and insert.
+       *  @return  Iterator after writing.
+      */
       iter_type 
       put(iter_type __s, ios_base& __f, char_type __fill, 
 	  const void* __v) const
@@ -2012,9 +2439,24 @@ namespace std
       _M_pad(char_type __fill, streamsize __w, ios_base& __io, 
 	     char_type* __new, const char_type* __cs, int& __len) const;
 
+      /// Destructor.
       virtual 
       ~num_put() { };
 
+      //@{
+      /**
+       *  @brief  Numeric formatting.
+       *
+       *  These functions do the work of formatting numeric values and
+       *  inserting them into a stream. This function is a hook for derived
+       *  classes to change the value returned.
+       *
+       *  @param  s  Stream to write to.
+       *  @param  io  Source of locale and flags.
+       *  @param  fill  Char_type to use for filling.
+       *  @param  v  Value to format and insert.
+       *  @return  Iterator after writing.
+      */
       virtual iter_type 
       do_put(iter_type, ios_base&, char_type __fill, bool __v) const;
 
@@ -2040,19 +2482,35 @@ namespace std
 
       virtual iter_type 
       do_put(iter_type, ios_base&, char_type __fill, const void* __v) const;
+      //@}
     };
 
   template <typename _CharT, typename _OutIter>
     locale::id num_put<_CharT, _OutIter>::id;
 
 
+  /**
+   *  @brief  Facet for localized string comparison.
+   *
+   *  This facet encapsulates the code to compare strings in a localized
+   *  manner.
+   *
+   *  The collate template uses protected virtual functions to provide
+   *  the actual results.  The public accessors forward the call to
+   *  the virtual functions.  These virtual functions are hooks for
+   *  developers to implement the behavior they require from the
+   *  collate facet.
+  */
   template<typename _CharT>
     class collate : public locale::facet
     {
     public:
       // Types:
+      //@{
+      /// Public typedefs
       typedef _CharT               	char_type;
       typedef basic_string<_CharT> 	string_type;
+      //@}
 
     protected:
       // Underlying "C" library locale information saved from
@@ -2060,27 +2518,80 @@ namespace std
       __c_locale			_M_c_locale_collate;
  
     public:
+      /// Numpunct facet id.
       static locale::id 		id;
 
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  This is the constructor provided by the standard.
+       *
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       collate(size_t __refs = 0)
       : facet(__refs)
       { _M_c_locale_collate = _S_get_c_locale(); }
 
+      /**
+       *  @brief  Internal constructor. Not for general use.
+       *
+       *  This is a constructor for use by the library itself to set up new
+       *  locales.
+       *
+       *  @param cloc  The "C" locale.
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       collate(__c_locale __cloc, size_t __refs = 0) 
       : facet(__refs)
       { _M_c_locale_collate = _S_clone_c_locale(__cloc); }
 
+      /**
+       *  @brief  Compare two strings.
+       *
+       *  This function compares two strings and returns the result by calling
+       *  collate::do_compare().
+       *
+       *  @param lo1  Start of string 1.
+       *  @param hi1  End of string 1.
+       *  @param lo2  Start of string 2.
+       *  @param hi2  End of string 2.
+       *  @return  1 if string1 > string2, -1 if string1 < string2, else 0.
+      */
       int 
       compare(const _CharT* __lo1, const _CharT* __hi1,
 	      const _CharT* __lo2, const _CharT* __hi2) const
       { return this->do_compare(__lo1, __hi1, __lo2, __hi2); }
 
+      /**
+       *  @brief  Transform string to comparable form.
+       *
+       *  This function is a wrapper for strxfrm functionality.  It takes the
+       *  input string and returns a modified string that can be directly
+       *  compared to other transformed strings.  In the "C" locale, this
+       *  function just returns a copy of the input string.  In some other
+       *  locales, it may replace two chars with one, change a char for
+       *  another, etc.  It does so by returning collate::do_transform().
+       *
+       *  @param lo  Start of string.
+       *  @param hi  End of string.
+       *  @return  Transformed string_type.
+      */
       string_type 
       transform(const _CharT* __lo, const _CharT* __hi) const
       { return this->do_transform(__lo, __hi); }
 
+      /**
+       *  @brief  Return hash of a string.
+       *
+       *  This function computes and returns a hash on the input string.  It
+       *  does so by returning collate::do_hash().
+       *
+       *  @param lo  Start of string.
+       *  @param hi  End of string.
+       *  @return  Hash value.
+      */
       long 
       hash(const _CharT* __lo, const _CharT* __hi) const
       { return this->do_hash(__lo, __hi); }
@@ -2093,17 +2604,52 @@ namespace std
       _M_transform(_CharT*, const _CharT*, size_t) const;
 
   protected:
+      /// Destructor.
       virtual
       ~collate() 
       { _S_destroy_c_locale(_M_c_locale_collate); }
 
+      /**
+       *  @brief  Compare two strings.
+       *
+       *  This function is a hook for derived classes to change the value
+       *  returned.  @see compare().
+       *
+       *  @param lo1  Start of string 1.
+       *  @param hi1  End of string 1.
+       *  @param lo2  Start of string 2.
+       *  @param hi2  End of string 2.
+       *  @return  1 if string1 > string2, -1 if string1 < string2, else 0.
+      */
       virtual int  
       do_compare(const _CharT* __lo1, const _CharT* __hi1,
 		 const _CharT* __lo2, const _CharT* __hi2) const;
 
+      /**
+       *  @brief  Transform string to comparable form.
+       *
+       *  This function is a hook for derived classes to change the value
+       *  returned.
+       *
+       *  @param lo1  Start of string 1.
+       *  @param hi1  End of string 1.
+       *  @param lo2  Start of string 2.
+       *  @param hi2  End of string 2.
+       *  @return  1 if string1 > string2, -1 if string1 < string2, else 0.
+      */
       virtual string_type 
       do_transform(const _CharT* __lo, const _CharT* __hi) const;
 
+      /**
+       *  @brief  Return hash of a string.
+       *
+       *  This function computes and returns a hash on the input string.  This
+       *  function is a hook for derived classes to change the value returned.
+       *
+       *  @param lo  Start of string.
+       *  @param hi  End of string.
+       *  @return  Hash value.
+      */
       virtual long   
       do_hash(const _CharT* __lo, const _CharT* __hi) const;
     };
@@ -2134,8 +2680,11 @@ namespace std
     class collate_byname : public collate<_CharT>
     {
     public:
+      //@{
+      /// Public typedefs
       typedef _CharT               char_type;
       typedef basic_string<_CharT> string_type;
+      //@}
 
       explicit 
       collate_byname(const char* __s, size_t __refs = 0)
@@ -2154,6 +2703,12 @@ namespace std
     };
 
 
+  /**
+   *  @brief  Time format ordering data.
+   *
+   *  This class provides an enum representing different orderings of day,
+   *  month, and year.
+  */
   class time_base
   {
   public:
@@ -2286,6 +2841,7 @@ namespace std
       const char*			_M_name_timepunct;
 
     public:
+      /// Numpunct facet id.
       static locale::id 		id;
 
       explicit 
@@ -2294,6 +2850,16 @@ namespace std
       explicit 
       __timepunct(__cache_type* __cache, size_t __refs = 0);
 
+      /**
+       *  @brief  Internal constructor. Not for general use.
+       *
+       *  This is a constructor for use by the library itself to set up new
+       *  locales.
+       *
+       *  @param cloc  The "C" locale.
+       *  @param s  The name of a locale.
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       __timepunct(__c_locale __cloc, const char* __s, size_t __refs = 0);
 
@@ -2425,73 +2991,303 @@ namespace std
   // Include host and configuration specific timepunct functions.
   #include <bits/time_members.h>
 
+  /**
+   *  @brief  Facet for parsing dates and times.
+   *
+   *  This facet encapsulates the code to parse and return a date or
+   *  time from a string.  It is used by the istream numeric
+   *  extraction operators.
+   *
+   *  The time_get template uses protected virtual functions to provide the
+   *  actual results.  The public accessors forward the call to the virtual
+   *  functions.  These virtual functions are hooks for developers to
+   *  implement the behavior they require from the time_get facet.
+  */
   template<typename _CharT, typename _InIter>
     class time_get : public locale::facet, public time_base
     {
     public:
       // Types:
+      //@{
+      /// Public typedefs
       typedef _CharT     		char_type;
       typedef _InIter    		iter_type;
+      //@}
       typedef basic_string<_CharT> 	__string_type;
 
+      /// Numpunct facet id.
       static locale::id 		id;
 
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  This is the constructor provided by the standard.
+       *
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       time_get(size_t __refs = 0) 
       : facet (__refs) { }
 
+      /**
+       *  @brief  Return preferred order of month, day, and year.
+       *
+       *  This function returns an enum from timebase::dateorder giving the
+       *  preferred ordering if the format "x" given to time_put::put() only
+       *  uses month, day, and year.  If the format "x" for the associated
+       *  locale uses other fields, this function returns
+       *  timebase::dateorder::noorder.  
+       *
+       *  NOTE: The library always returns noorder at the moment.
+       *
+       *  @return  A member of timebase::dateorder.
+      */
       dateorder 
       date_order()  const
       { return this->do_date_order(); }
 
+      /**
+       *  @brief  Parse input time string.
+       *
+       *  This function parses a time according to the format "x" and puts the
+       *  results into a user-supplied struct tm.  The result is returned by
+       *  calling time_get::do_get_time().
+       *
+       *  If there is a valid time string according to format "x", @a tm will
+       *  be filled in accordingly and the returned iterator will point to the
+       *  first character beyond the time string.  If an error occurs before
+       *  the end, err |= ios_base::failbit.  If parsing reads all the
+       *  characters, err |= ios_base::eofbit.
+       *
+       *  @param  beg  Start of string to parse.
+       *  @param  end  End of string to parse.
+       *  @param  io  Source of the locale.
+       *  @param  err  Error flags to set.
+       *  @param  tm  Pointer to struct tm to fill in.
+       *  @return  Iterator to first char beyond time string.
+      */
       iter_type 
       get_time(iter_type __beg, iter_type __end, ios_base& __io, 
 	       ios_base::iostate& __err, tm* __tm)  const
       { return this->do_get_time(__beg, __end, __io, __err, __tm); }
 
+      /**
+       *  @brief  Parse input date string.
+       *
+       *  This function parses a date according to the format "X" and puts the
+       *  results into a user-supplied struct tm.  The result is returned by
+       *  calling time_get::do_get_date().
+       *
+       *  If there is a valid date string according to format "X", @a tm will
+       *  be filled in accordingly and the returned iterator will point to the
+       *  first character beyond the date string.  If an error occurs before
+       *  the end, err |= ios_base::failbit.  If parsing reads all the
+       *  characters, err |= ios_base::eofbit.
+       *
+       *  @param  beg  Start of string to parse.
+       *  @param  end  End of string to parse.
+       *  @param  io  Source of the locale.
+       *  @param  err  Error flags to set.
+       *  @param  tm  Pointer to struct tm to fill in.
+       *  @return  Iterator to first char beyond date string.
+      */
       iter_type 
       get_date(iter_type __beg, iter_type __end, ios_base& __io,
 	       ios_base::iostate& __err, tm* __tm)  const
       { return this->do_get_date(__beg, __end, __io, __err, __tm); }
 
+      /**
+       *  @brief  Parse input weekday string.
+       *
+       *  This function parses a weekday name and puts the results into a
+       *  user-supplied struct tm.  The result is returned by calling
+       *  time_get::do_get_weekday().
+       *
+       *  Parsing starts by parsing an abbreviated weekday name.  If a valid
+       *  abbreviation is followed by a character that would lead to the full
+       *  weekday name, parsing continues until the full name is found or an
+       *  error occurs.  Otherwise parsing finishes at the end of the
+       *  abbreviated name.
+       *
+       *  If an error occurs before the end, err |= ios_base::failbit.  If
+       *  parsing reads all the characters, err |= ios_base::eofbit.
+       *
+       *  @param  beg  Start of string to parse.
+       *  @param  end  End of string to parse.
+       *  @param  io  Source of the locale.
+       *  @param  err  Error flags to set.
+       *  @param  tm  Pointer to struct tm to fill in.
+       *  @return  Iterator to first char beyond weekday name.
+      */
       iter_type 
       get_weekday(iter_type __beg, iter_type __end, ios_base& __io,
 		  ios_base::iostate& __err, tm* __tm) const
       { return this->do_get_weekday(__beg, __end, __io, __err, __tm); }
 
+      /**
+       *  @brief  Parse input month string.
+       *
+       *  This function parses a month name and puts the results into a
+       *  user-supplied struct tm.  The result is returned by calling
+       *  time_get::do_get_monthname().
+       *
+       *  Parsing starts by parsing an abbreviated month name.  If a valid
+       *  abbreviation is followed by a character that would lead to the full
+       *  month name, parsing continues until the full name is found or an
+       *  error occurs.  Otherwise parsing finishes at the end of the
+       *  abbreviated name.
+       *
+       *  If an error occurs before the end, err |= ios_base::failbit.  If
+       *  parsing reads all the characters, err |=
+       *  ios_base::eofbit.
+       *
+       *  @param  beg  Start of string to parse.
+       *  @param  end  End of string to parse.
+       *  @param  io  Source of the locale.
+       *  @param  err  Error flags to set.
+       *  @param  tm  Pointer to struct tm to fill in.
+       *  @return  Iterator to first char beyond month name.
+      */
       iter_type 
       get_monthname(iter_type __beg, iter_type __end, ios_base& __io, 
 		    ios_base::iostate& __err, tm* __tm) const
       { return this->do_get_monthname(__beg, __end, __io, __err, __tm); }
 
+      /**
+       *  @brief  Parse input year string.
+       *
+       *  This function reads up to 4 characters to parse a year string and
+       *  puts the results into a user-supplied struct tm.  The result is
+       *  returned by calling time_get::do_get_year().
+       *
+       *  4 consecutive digits are interpreted as a full year.  If there are
+       *  exactly 2 consecutive digits, the library interprets this as the
+       *  number of years since 1900.
+       *
+       *  If an error occurs before the end, err |= ios_base::failbit.  If
+       *  parsing reads all the characters, err |= ios_base::eofbit.
+       *
+       *  @param  beg  Start of string to parse.
+       *  @param  end  End of string to parse.
+       *  @param  io  Source of the locale.
+       *  @param  err  Error flags to set.
+       *  @param  tm  Pointer to struct tm to fill in.
+       *  @return  Iterator to first char beyond year.
+      */
       iter_type 
       get_year(iter_type __beg, iter_type __end, ios_base& __io,
 	       ios_base::iostate& __err, tm* __tm) const
       { return this->do_get_year(__beg, __end, __io, __err, __tm); }
 
     protected:
+      /// Destructor.
       virtual 
       ~time_get() { }
 
+      /**
+       *  @brief  Return preferred order of month, day, and year.
+       *
+       *  This function returns an enum from timebase::dateorder giving the
+       *  preferred ordering if the format "x" given to time_put::put() only
+       *  uses month, day, and year.  This function is a hook for derived
+       *  classes to change the value returned.
+       *
+       *  @return  A member of timebase::dateorder.
+      */
       virtual dateorder 
       do_date_order() const;
 
+      /**
+       *  @brief  Parse input time string.
+       *
+       *  This function parses a time according to the format "x" and puts the
+       *  results into a user-supplied struct tm.  This function is a hook for
+       *  derived classes to change the value returned.  @see get_time() for
+       *  details.
+       *
+       *  @param  beg  Start of string to parse.
+       *  @param  end  End of string to parse.
+       *  @param  io  Source of the locale.
+       *  @param  err  Error flags to set.
+       *  @param  tm  Pointer to struct tm to fill in.
+       *  @return  Iterator to first char beyond time string.
+      */
       virtual iter_type 
       do_get_time(iter_type __beg, iter_type __end, ios_base& __io,
 		  ios_base::iostate& __err, tm* __tm) const;
 
+      /**
+       *  @brief  Parse input date string.
+       *
+       *  This function parses a date according to the format "X" and puts the
+       *  results into a user-supplied struct tm.  This function is a hook for
+       *  derived classes to change the value returned.  @see get_date() for
+       *  details.
+       *
+       *  @param  beg  Start of string to parse.
+       *  @param  end  End of string to parse.
+       *  @param  io  Source of the locale.
+       *  @param  err  Error flags to set.
+       *  @param  tm  Pointer to struct tm to fill in.
+       *  @return  Iterator to first char beyond date string.
+      */
       virtual iter_type 
       do_get_date(iter_type __beg, iter_type __end, ios_base& __io,
 		  ios_base::iostate& __err, tm* __tm) const;
 
+      /**
+       *  @brief  Parse input weekday string.
+       *
+       *  This function parses a weekday name and puts the results into a
+       *  user-supplied struct tm.  This function is a hook for derived
+       *  classes to change the value returned.  @see get_weekday() for
+       *  details.
+       *
+       *  @param  beg  Start of string to parse.
+       *  @param  end  End of string to parse.
+       *  @param  io  Source of the locale.
+       *  @param  err  Error flags to set.
+       *  @param  tm  Pointer to struct tm to fill in.
+       *  @return  Iterator to first char beyond weekday name.
+      */
       virtual iter_type 
       do_get_weekday(iter_type __beg, iter_type __end, ios_base&,
 		     ios_base::iostate& __err, tm* __tm) const;
 
+      /**
+       *  @brief  Parse input month string.
+       *
+       *  This function parses a month name and puts the results into a
+       *  user-supplied struct tm.  This function is a hook for derived
+       *  classes to change the value returned.  @see get_monthname() for
+       *  details.
+       *
+       *  @param  beg  Start of string to parse.
+       *  @param  end  End of string to parse.
+       *  @param  io  Source of the locale.
+       *  @param  err  Error flags to set.
+       *  @param  tm  Pointer to struct tm to fill in.
+       *  @return  Iterator to first char beyond month name.
+      */
       virtual iter_type 
       do_get_monthname(iter_type __beg, iter_type __end, ios_base&, 
 		       ios_base::iostate& __err, tm* __tm) const;
 
+      /**
+       *  @brief  Parse input year string.
+       *
+       *  This function reads up to 4 characters to parse a year string and
+       *  puts the results into a user-supplied struct tm.  This function is a
+       *  hook for derived classes to change the value returned.  @see
+       *  get_year() for details.
+       *
+       *  @param  beg  Start of string to parse.
+       *  @param  end  End of string to parse.
+       *  @param  io  Source of the locale.
+       *  @param  err  Error flags to set.
+       *  @param  tm  Pointer to struct tm to fill in.
+       *  @return  Iterator to first char beyond year.
+      */
       virtual iter_type 
       do_get_year(iter_type __beg, iter_type __end, ios_base& __io,
 		  ios_base::iostate& __err, tm* __tm) const;
@@ -2538,34 +3334,104 @@ namespace std
       ~time_get_byname() { }
     };
 
+  /**
+   *  @brief  Facet for outputting dates and times.
+   *
+   *  This facet encapsulates the code to format and output dates and times
+   *  according to formats used by strftime().
+   *
+   *  The time_put template uses protected virtual functions to provide the
+   *  actual results.  The public accessors forward the call to the virtual
+   *  functions.  These virtual functions are hooks for developers to
+   *  implement the behavior they require from the time_put facet.
+  */
   template<typename _CharT, typename _OutIter>
     class time_put : public locale::facet, public time_base
     {
     public:
       // Types:
+      //@{
+      /// Public typedefs
       typedef _CharT     		char_type;
       typedef _OutIter   		iter_type;
+      //@}
 
+      /// Numpunct facet id.
       static locale::id 	     	id;
 
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  This is the constructor provided by the standard.
+       *
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       time_put(size_t __refs = 0) 
       : facet(__refs) { }
 
+      /**
+       *  @brief  Format and output a time or date.
+       *
+       *  This function formats the data in struct tm according to the
+       *  provided format string.  The format string is interpreted as by
+       *  strftime().
+       *
+       *  @param  s  The stream to write to.
+       *  @param  io  Source of locale.
+       *  @param  fill  char_type to use for padding.
+       *  @param  tm  Struct tm with date and time info to format.
+       *  @param  beg  Start of format string.
+       *  @param  end  End of format string.
+       *  @return  Iterator after writing.
+       */
       iter_type 
       put(iter_type __s, ios_base& __io, char_type __fill, const tm* __tm, 
 	  const _CharT* __beg, const _CharT* __end) const;
 
+      /**
+       *  @brief  Format and output a time or date.
+       *
+       *  This function formats the data in struct tm according to the
+       *  provided format char and optional modifier.  The format and modifier
+       *  are interpreted as by strftime().  It does so by returning
+       *  time_put::do_put().
+       *
+       *  @param  s  The stream to write to.
+       *  @param  io  Source of locale.
+       *  @param  fill  char_type to use for padding.
+       *  @param  tm  Struct tm with date and time info to format.
+       *  @param  format  Format char.
+       *  @param  mod  Optional modifier char.
+       *  @return  Iterator after writing.
+       */
       iter_type 
       put(iter_type __s, ios_base& __io, char_type __fill,
 	  const tm* __tm, char __format, char __mod = 0) const
       { return this->do_put(__s, __io, __fill, __tm, __format, __mod); }
 
     protected:
+      /// Destructor.
       virtual 
       ~time_put()
       { }
 
+      /**
+       *  @brief  Format and output a time or date.
+       *
+       *  This function formats the data in struct tm according to the
+       *  provided format char and optional modifier.  This function is a hook
+       *  for derived classes to change the value returned.  @see put() for
+       *  more details.
+       *
+       *  @param  s  The stream to write to.
+       *  @param  io  Source of locale.
+       *  @param  fill  char_type to use for padding.
+       *  @param  tm  Struct tm with date and time info to format.
+       *  @param  format  Format char.
+       *  @param  mod  Optional modifier char.
+       *  @return  Iterator after writing.
+       */
       virtual iter_type 
       do_put(iter_type __s, ios_base& __io, char_type __fill, const tm* __tm, 
 	     char __format, char __mod) const;
@@ -2593,6 +3459,16 @@ namespace std
     };
 
 
+  /**
+   *  @brief  Money format ordering data.
+   *
+   *  This class contains an ordered array of 4 fields to represent the
+   *  pattern for formatting a money amount.  Each field may contain one entry
+   *  from the part enum.  symbol, sign, and value must be present and the
+   *  remaining field must contain either none or space.  @see
+   *  moneypunct::pos_format() and moneypunct::neg_format() for details of how
+   *  these fields are interpreted.
+  */
   class money_base
   {
   public:
@@ -2646,108 +3522,350 @@ namespace std
 	}
     }
 
+  /**
+   *  @brief  Facet for formatting data for money amounts.
+   *
+   *  This facet encapsulates the punctuation, grouping and other formatting
+   *  features of money amount string representations.
+  */
   template<typename _CharT, bool _Intl>
     class moneypunct : public locale::facet, public money_base
     {
     public:
       // Types:
+      //@{
+      /// Public typedefs
       typedef _CharT 		       	char_type;
       typedef basic_string<_CharT> 	string_type;
+      //@}
       typedef __moneypunct_cache<_CharT>	__cache_type;
 
     private:
       __cache_type*			_M_data;
 
     public:
+      /// This value is provided by the standard, but no reason for its
+      /// existence.
       static const bool 		intl = _Intl;
+      /// Numpunct facet id.
       static locale::id 		id;
 
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  This is the constructor provided by the standard.
+       *
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       moneypunct(size_t __refs = 0) : facet(__refs), _M_data(NULL)
       { _M_initialize_moneypunct(); }
 
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  This is an internal constructor.
+       *
+       *  @param cache  Cache for optimization.
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       moneypunct(__cache_type* __cache, size_t __refs = 0) 
       : facet(__refs), _M_data(__cache)
       { _M_initialize_moneypunct(); }
 
+      /**
+       *  @brief  Internal constructor. Not for general use.
+       *
+       *  This is a constructor for use by the library itself to set up new
+       *  locales.
+       *
+       *  @param cloc  The "C" locale.
+       *  @param s  The name of a locale.
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       moneypunct(__c_locale __cloc, const char* __s, size_t __refs = 0) 
       : facet(__refs), _M_data(NULL)
       { _M_initialize_moneypunct(__cloc, __s); }
 
+      /**
+       *  @brief  Return decimal point character.
+       *
+       *  This function returns a char_type to use as a decimal point.  It
+       *  does so by returning returning
+       *  moneypunct<char_type>::do_decimal_point().
+       *
+       *  @return  @a char_type representing a decimal point.
+      */
       char_type
       decimal_point() const
       { return this->do_decimal_point(); }
       
+      /**
+       *  @brief  Return thousands separator character.
+       *
+       *  This function returns a char_type to use as a thousands separator.  It
+       *  does so by returning returning
+       *  moneypunct<char_type>::do_thousands_sep().
+       *
+       *  @return  char_type representing a thousands separator.
+      */
       char_type
       thousands_sep() const
       { return this->do_thousands_sep(); }
       
+      /**
+       *  @brief  Return grouping specification.
+       *
+       *  This function returns a string representing groupings for the
+       *  integer part of an amount.  Groupings indicate where thousands
+       *  separators should be inserted.
+       *
+       *  Each char in the return string is interpret as an integer rather
+       *  than a character.  These numbers represent the number of digits in a
+       *  group.  The first char in the string represents the number of digits
+       *  in the least significant group.  If a char is negative, it indicates
+       *  an unlimited number of digits for the group.  If more chars from the
+       *  string are required to group a number, the last char is used
+       *  repeatedly.
+       *
+       *  For example, if the grouping() returns "\003\002" and is applied to
+       *  the number 123456789, this corresponds to 12,34,56,789.  Note that
+       *  if the string was "32", this would put more than 50 digits into the
+       *  least significant group if the character set is ASCII.
+       *
+       *  The string is returned by calling
+       *  moneypunct<char_type>::do_grouping().
+       *
+       *  @return  string representing grouping specification.
+      */
       string 
       grouping() const
       { return this->do_grouping(); }
 
+      /**
+       *  @brief  Return currency symbol string.
+       *
+       *  This function returns a string_type to use as a currency symbol.  It
+       *  does so by returning returning
+       *  moneypunct<char_type>::do_curr_symbol().
+       *
+       *  @return  @a string_type representing a currency symbol.
+      */
       string_type  
       curr_symbol() const
       { return this->do_curr_symbol(); }
 
+      /**
+       *  @brief  Return positive sign string.
+       *
+       *  This function returns a string_type to use as a sign for positive
+       *  amounts.  It does so by returning returning
+       *  moneypunct<char_type>::do_positive_sign().
+       *
+       *  If the return value contains more than one character, the first
+       *  character appears in the position indicated by pos_format() and the
+       *  remainder appear at the end of the formatted string.
+       *
+       *  @return  @a string_type representing a positive sign.
+      */
       string_type  
       positive_sign() const
       { return this->do_positive_sign(); }
 
+      /**
+       *  @brief  Return negative sign string.
+       *
+       *  This function returns a string_type to use as a sign for negative
+       *  amounts.  It does so by returning returning
+       *  moneypunct<char_type>::do_negative_sign().
+       *
+       *  If the return value contains more than one character, the first
+       *  character appears in the position indicated by neg_format() and the
+       *  remainder appear at the end of the formatted string.
+       *
+       *  @return  @a string_type representing a negative sign.
+      */
       string_type  
       negative_sign() const
       { return this->do_negative_sign(); }
 
-      int          
+      /**
+       *  @brief  Return number of digits in fraction.
+       *
+       *  This function returns the exact number of digits that make up the
+       *  fractional part of a money amount.  It does so by returning
+       *  returning moneypunct<char_type>::do_frac_digits().
+       *
+       *  The fractional part of a money amount is optional.  But if it is
+       *  present, there must be frac_digits() digits.
+       *
+       *  @return  Number of digits in amount fraction.
+      */
+      int
       frac_digits() const
       { return this->do_frac_digits(); }
 
-      pattern      
+      //@{
+      /**
+       *  @brief  Return pattern for money values.
+       *
+       *  This function returns a pattern describing the formatting of a
+       *  positive or negative valued money amount.  It does so by returning
+       *  returning moneypunct<char_type>::do_pos_format() or
+       *  moneypunct<char_type>::do_neg_format().
+       *
+       *  The pattern has 4 fields describing the ordering of symbol, sign,
+       *  value, and none or space.  There must be one of each in the pattern.
+       *  The none and space enums may not appear in the first field and space
+       *  may not appear in the final field.
+       *
+       *  The parts of a money string must appear in the order indicated by
+       *  the fields of the pattern.  The symbol field indicates that the
+       *  value of curr_symbol() may be present.  The sign field indicates
+       *  that the value of positive_sign() or negative_sign() must be
+       *  present.  The value field indicates that the absolute value of the
+       *  money amount is present.  none indicates 0 or more whitespace
+       *  characters, except at the end, where it permits no whitespace.
+       *  space indicates that 1 or more whitespace characters must be
+       *  present.
+       *
+       *  For example, for the US locale and pos_format() pattern
+       *  {symbol,sign,value,none}, curr_symbol() == '$' positive_sign() ==
+       *  '+', and value 10.01, and options set to force the symbol, the
+       *  corresponding string is "$+10.01".
+       *
+       *  @return  Pattern for money values.
+      */
+      pattern
       pos_format() const
       { return this->do_pos_format(); }
 
       pattern      
       neg_format() const
       { return this->do_neg_format(); }
+      //@}
 
     protected:
+      /// Destructor.
       virtual 
       ~moneypunct();
 
+      /**
+       *  @brief  Return decimal point character.
+       *
+       *  Returns a char_type to use as a decimal point.  This function is a
+       *  hook for derived classes to change the value returned.
+       *
+       *  @return  @a char_type representing a decimal point.
+      */
       virtual char_type
       do_decimal_point() const
       { return _M_data->_M_decimal_point; }
       
+      /**
+       *  @brief  Return thousands separator character.
+       *
+       *  Returns a char_type to use as a thousands separator.  This function
+       *  is a hook for derived classes to change the value returned.
+       *
+       *  @return  @a char_type representing a thousands separator.
+      */
       virtual char_type
       do_thousands_sep() const
       { return _M_data->_M_thousands_sep; }
       
+      /**
+       *  @brief  Return grouping specification.
+       *
+       *  Returns a string representing groupings for the integer part of a
+       *  number.  This function is a hook for derived classes to change the
+       *  value returned.  @see grouping() for details.
+       *
+       *  @return  String representing grouping specification.
+      */
       virtual string 
       do_grouping() const
       { return _M_data->_M_grouping; }
 
+      /**
+       *  @brief  Return currency symbol string.
+       *
+       *  This function returns a string_type to use as a currency symbol.
+       *  This function is a hook for derived classes to change the value
+       *  returned.  @see curr_symbol() for details.
+       *
+       *  @return  @a string_type representing a currency symbol.
+      */
       virtual string_type  
       do_curr_symbol()   const
       { return _M_data->_M_curr_symbol; }
 
+      /**
+       *  @brief  Return positive sign string.
+       *
+       *  This function returns a string_type to use as a sign for positive
+       *  amounts.  This function is a hook for derived classes to change the
+       *  value returned.  @see positive_sign() for details.
+       *
+       *  @return  @a string_type representing a positive sign.
+      */
       virtual string_type  
       do_positive_sign() const
       { return _M_data->_M_positive_sign; }
 
+      /**
+       *  @brief  Return negative sign string.
+       *
+       *  This function returns a string_type to use as a sign for negative
+       *  amounts.  This function is a hook for derived classes to change the
+       *  value returned.  @see negative_sign() for details.
+       *
+       *  @return  @a string_type representing a negative sign.
+      */
       virtual string_type  
       do_negative_sign() const
       { return _M_data->_M_negative_sign; }
 
+      /**
+       *  @brief  Return number of digits in fraction.
+       *
+       *  This function returns the exact number of digits that make up the
+       *  fractional part of a money amount.  This function is a hook for
+       *  derived classes to change the value returned.  @see frac_digits()
+       *  for details.
+       *
+       *  @return  Number of digits in amount fraction.
+      */
       virtual int          
       do_frac_digits() const
       { return _M_data->_M_frac_digits; }
 
+      /**
+       *  @brief  Return pattern for money values.
+       *
+       *  This function returns a pattern describing the formatting of a
+       *  positive valued money amount.  This function is a hook for derived
+       *  classes to change the value returned.  @see pos_format() for
+       *  details.
+       *
+       *  @return  Pattern for money values.
+      */
       virtual pattern      
       do_pos_format() const
       { return _M_data->_M_pos_format; }
 
+      /**
+       *  @brief  Return pattern for money values.
+       *
+       *  This function returns a pattern describing the formatting of a
+       *  negative valued money amount.  This function is a hook for derived
+       *  classes to change the value returned.  @see neg_format() for
+       *  details.
+       *
+       *  @return  Pattern for money values.
+      */
       virtual pattern      
       do_neg_format() const
       { return _M_data->_M_neg_format; }
@@ -2826,38 +3944,128 @@ namespace std
   template<typename _CharT, bool _Intl>
     const bool moneypunct_byname<_CharT, _Intl>::intl;
 
+  /**
+   *  @brief  Facet for parsing monetary amounts.
+   *
+   *  This facet encapsulates the code to parse and return a monetary
+   *  amount from a string.
+   *
+   *  The money_get template uses protected virtual functions to
+   *  provide the actual results.  The public accessors forward the
+   *  call to the virtual functions.  These virtual functions are
+   *  hooks for developers to implement the behavior they require from
+   *  the money_get facet.
+  */
   template<typename _CharT, typename _InIter>
     class money_get : public locale::facet
     {
     public:
       // Types:
+      //@{
+      /// Public typedefs
       typedef _CharT        		char_type;
       typedef _InIter       		iter_type;
       typedef basic_string<_CharT> 	string_type;
+      //@}
 
+      /// Numpunct facet id.
       static locale::id 		id;
 
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  This is the constructor provided by the standard.
+       *
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       money_get(size_t __refs = 0) : facet(__refs) { }
 
-      iter_type 
+      /**
+       *  @brief  Read and parse a monetary value.
+       *
+       *  This function reads characters from @a s, interprets them as a
+       *  monetary value according to moneypunct and ctype facets retrieved
+       *  from io.getloc(), and returns the result in @a units as an integral
+       *  value moneypunct::frac_digits() * the actual amount.  For example,
+       *  the string $10.01 in a US locale would store 1001 in @a units.
+       *
+       *  Any characters not part of a valid money amount are not consumed.
+       *
+       *  If a money value cannot be parsed from the input stream, sets
+       *  err=(err|io.failbit).  If the stream is consumed before finishing
+       *  parsing,  sets err=(err|io.failbit|io.eofbit).  @a units is
+       *  unchanged if parsing fails.
+       *
+       *  This function works by returning the result of do_get().
+       *
+       *  @param  s  Start of characters to parse.
+       *  @param  end  End of characters to parse.
+       *  @param  intl  Parameter to use_facet<moneypunct<CharT,intl> >.
+       *  @param  io  Source of facets and io state.
+       *  @param  err  Error field to set if parsing fails.
+       *  @param  units  Place to store result of parsing.
+       *  @return  Iterator referencing first character beyond valid money
+       *  	   amount. 
+       */
+      iter_type
       get(iter_type __s, iter_type __end, bool __intl, ios_base& __io, 
 	  ios_base::iostate& __err, long double& __units) const
       { return this->do_get(__s, __end, __intl, __io, __err, __units); }
 
+      /**
+       *  @brief  Read and parse a monetary value.
+       *
+       *  This function reads characters from @a s, interprets them as a
+       *  monetary value according to moneypunct and ctype facets retrieved
+       *  from io.getloc(), and returns the result in @a digits.  For example,
+       *  the string $10.01 in a US locale would store "1001" in @a digits.
+       *
+       *  Any characters not part of a valid money amount are not consumed.
+       *
+       *  If a money value cannot be parsed from the input stream, sets
+       *  err=(err|io.failbit).  If the stream is consumed before finishing
+       *  parsing,  sets err=(err|io.failbit|io.eofbit).
+       *
+       *  This function works by returning the result of do_get().
+       *
+       *  @param  s  Start of characters to parse.
+       *  @param  end  End of characters to parse.
+       *  @param  intl  Parameter to use_facet<moneypunct<CharT,intl> >.
+       *  @param  io  Source of facets and io state.
+       *  @param  err  Error field to set if parsing fails.
+       *  @param  digits  Place to store result of parsing.
+       *  @return  Iterator referencing first character beyond valid money
+       *  	   amount. 
+       */
       iter_type 
       get(iter_type __s, iter_type __end, bool __intl, ios_base& __io, 
 	  ios_base::iostate& __err, string_type& __digits) const
       { return this->do_get(__s, __end, __intl, __io, __err, __digits); }
 
     protected:
+      /// Destructor.
       virtual 
       ~money_get() { }
 
+      /**
+       *  @brief  Read and parse a monetary value.
+       *
+       *  This function reads and parses characters representing a monetary
+       *  value.  This function is a hook for derived classes to change the
+       *  value returned.  @see get() for details.
+       */
       virtual iter_type 
       do_get(iter_type __s, iter_type __end, bool __intl, ios_base& __io, 
 	     ios_base::iostate& __err, long double& __units) const;
 
+      /**
+       *  @brief  Read and parse a monetary value.
+       *
+       *  This function reads and parses characters representing a monetary
+       *  value.  This function is a hook for derived classes to change the
+       *  value returned.  @see get() for details.
+       */
       virtual iter_type 
       do_get(iter_type __s, iter_type __end, bool __intl, ios_base& __io, 
 	     ios_base::iostate& __err, string_type& __digits) const;
@@ -2866,37 +4074,131 @@ namespace std
   template<typename _CharT, typename _InIter>
     locale::id money_get<_CharT, _InIter>::id;
 
+  /**
+   *  @brief  Facet for outputting monetary amounts.
+   *
+   *  This facet encapsulates the code to format and output a monetary
+   *  amount.
+   *
+   *  The money_put template uses protected virtual functions to
+   *  provide the actual results.  The public accessors forward the
+   *  call to the virtual functions.  These virtual functions are
+   *  hooks for developers to implement the behavior they require from
+   *  the money_put facet.
+  */
   template<typename _CharT, typename _OutIter>
     class money_put : public locale::facet
     {
     public:
+      //@{
+      /// Public typedefs
       typedef _CharT              	char_type;
       typedef _OutIter            	iter_type;
       typedef basic_string<_CharT>	string_type;
+      //@}
 
+      /// Numpunct facet id.
       static locale::id 		id;
 
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  This is the constructor provided by the standard.
+       *
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       money_put(size_t __refs = 0) : facet(__refs) { }
 
+      /**
+       *  @brief  Format and output a monetary value.
+       *
+       *  This function formats @a units as a monetary value according to
+       *  moneypunct and ctype facets retrieved from io.getloc(), and writes
+       *  the resulting characters to @a s.  For example, the value 1001 in a
+       *  US locale would write "$10.01" to @a s.
+       *
+       *  This function works by returning the result of do_put().
+       *
+       *  @param  s  The stream to write to.
+       *  @param  intl  Parameter to use_facet<moneypunct<CharT,intl> >.
+       *  @param  io  Source of facets and io state.
+       *  @param  fill  char_type to use for padding.
+       *  @param  units  Place to store result of parsing.
+       *  @return  Iterator after writing.
+       */
       iter_type 
       put(iter_type __s, bool __intl, ios_base& __io,
 	  char_type __fill, long double __units) const
       { return this->do_put(__s, __intl, __io, __fill, __units); }
 
+      /**
+       *  @brief  Format and output a monetary value.
+       *
+       *  This function formats @a digits as a monetary value according to
+       *  moneypunct and ctype facets retrieved from io.getloc(), and writes
+       *  the resulting characters to @a s.  For example, the string "1001" in
+       *  a US locale would write "$10.01" to @a s.
+       *
+       *  This function works by returning the result of do_put().
+       *
+       *  @param  s  The stream to write to.
+       *  @param  intl  Parameter to use_facet<moneypunct<CharT,intl> >.
+       *  @param  io  Source of facets and io state.
+       *  @param  fill  char_type to use for padding.
+       *  @param  units  Place to store result of parsing.
+       *  @return  Iterator after writing.
+       */
       iter_type 
       put(iter_type __s, bool __intl, ios_base& __io,
 	  char_type __fill, const string_type& __digits) const
       { return this->do_put(__s, __intl, __io, __fill, __digits); }
 
     protected:
+      /// Destructor.
       virtual 
       ~money_put() { }
 
+      /**
+       *  @brief  Format and output a monetary value.
+       *
+       *  This function formats @a units as a monetary value according to
+       *  moneypunct and ctype facets retrieved from io.getloc(), and writes
+       *  the resulting characters to @a s.  For example, the value 1001 in a
+       *  US locale would write "$10.01" to @a s.
+       *
+       *  This function is a hook for derived classes to change the value
+       *  returned.  @see put().
+       *
+       *  @param  s  The stream to write to.
+       *  @param  intl  Parameter to use_facet<moneypunct<CharT,intl> >.
+       *  @param  io  Source of facets and io state.
+       *  @param  fill  char_type to use for padding.
+       *  @param  units  Place to store result of parsing.
+       *  @return  Iterator after writing.
+       */
       virtual iter_type
       do_put(iter_type __s, bool __intl, ios_base& __io, char_type __fill,
 	     long double __units) const;
 
+      /**
+       *  @brief  Format and output a monetary value.
+       *
+       *  This function formats @a digits as a monetary value according to
+       *  moneypunct and ctype facets retrieved from io.getloc(), and writes
+       *  the resulting characters to @a s.  For example, the string "1001" in
+       *  a US locale would write "$10.01" to @a s.
+       *
+       *  This function is a hook for derived classes to change the value
+       *  returned.  @see put().
+       *
+       *  @param  s  The stream to write to.
+       *  @param  intl  Parameter to use_facet<moneypunct<CharT,intl> >.
+       *  @param  io  Source of facets and io state.
+       *  @param  fill  char_type to use for padding.
+       *  @param  units  Place to store result of parsing.
+       *  @return  Iterator after writing.
+       */
       virtual iter_type
       do_put(iter_type __s, bool __intl, ios_base& __io, char_type __fill,
 	     const string_type& __digits) const;
@@ -2905,19 +4207,44 @@ namespace std
   template<typename _CharT, typename _OutIter>
     locale::id money_put<_CharT, _OutIter>::id;
 
-
+  /**
+   *  @brief  Messages facet base class providing catalog typedef.
+   */
   struct messages_base
   {
     typedef int catalog;
   };
 
+  /**
+   *  @brief  Facet for handling message catalogs
+   *
+   *  This facet encapsulates the code to retrieve messages from
+   *  message catalogs.  The only thing defined by the standard for this facet
+   *  is the interface.  All underlying functionality is
+   *  implementation-defined.
+   *
+   *  This library currently implements 3 versions of the message facet.  The
+   *  first version (gnu) is a wrapper around gettext, provided by libintl.
+   *  The second version (ieee) is a wrapper around catgets.  The final
+   *  version (default) does no actual translation.  These implementations are
+   *  only provided for char and wchar_t instantiations.
+   *
+   *  The messages template uses protected virtual functions to
+   *  provide the actual results.  The public accessors forward the
+   *  call to the virtual functions.  These virtual functions are
+   *  hooks for developers to implement the behavior they require from
+   *  the messages facet.
+  */
   template<typename _CharT>
     class messages : public locale::facet, public messages_base
     {
     public:
       // Types:
+      //@{
+      /// Public typedefs
       typedef _CharT 			char_type;
       typedef basic_string<_CharT> 	string_type;
+      //@}
 
     protected:
       // Underlying "C" library locale information saved from
@@ -2926,41 +4253,137 @@ namespace std
       const char*			_M_name_messages;
 
     public:
+      /// Numpunct facet id.
       static locale::id 		id;
 
+      /**
+       *  @brief  Constructor performs initialization.
+       *
+       *  This is the constructor provided by the standard.
+       *
+       *  @param refs  Passed to the base facet class.
+      */
       explicit 
       messages(size_t __refs = 0);
 
       // Non-standard.
+      /**
+       *  @brief  Internal constructor.  Not for general use.
+       *
+       *  This is a constructor for use by the library itself to set up new
+       *  locales.
+       *
+       *  @param  cloc  The "C" locale.
+       *  @param  s  The name of a locale.
+       *  @param  refs  Refcount to pass to the base class.
+       */
       explicit 
       messages(__c_locale __cloc, const char* __s, size_t __refs = 0);
 
+      /*
+       *  @brief  Open a message catalog.
+       *
+       *  This function opens and returns a handle to a message catalog by
+       *  returning do_open(s, loc).
+       *
+       *  @param  s  The catalog to open.
+       *  @param  loc  Locale to use for character set conversions.
+       *  @return  Handle to the catalog or value < 0 if open fails.
+      */
       catalog 
       open(const basic_string<char>& __s, const locale& __loc) const
       { return this->do_open(__s, __loc); }
 
       // Non-standard and unorthodox, yet effective.
+      /*
+       *  @brief  Open a message catalog.
+       *
+       *  This non-standard function opens and returns a handle to a message
+       *  catalog by returning do_open(s, loc).  The third argument provides a
+       *  message catalog root directory for gnu gettext and is ignored
+       *  otherwise.
+       *
+       *  @param  s  The catalog to open.
+       *  @param  loc  Locale to use for character set conversions.
+       *  @param  dir  Message catalog root directory.
+       *  @return  Handle to the catalog or value < 0 if open fails.
+      */
       catalog 
       open(const basic_string<char>&, const locale&, const char*) const;
 
+      /*
+       *  @brief  Look up a string in a message catalog.
+       *
+       *  This function retrieves and returns a message from a catalog by
+       *  returning do_get(c, set, msgid, s).
+       *
+       *  For gnu, @a set and @a msgid are ignored.  Returns gettext(s).
+       *  For default, returns s. For ieee, returns catgets(c,set,msgid,s).
+       *
+       *  @param  c  The catalog to access.
+       *  @param  set  Implementation-defined.
+       *  @param  msgid  Implementation-defined.
+       *  @param  s  Default return value if retrieval fails.
+       *  @return  Retrieved message or @a s if get fails.
+      */
       string_type  
       get(catalog __c, int __set, int __msgid, const string_type& __s) const
       { return this->do_get(__c, __set, __msgid, __s); }
 
+      /*
+       *  @brief  Close a message catalog.
+       *
+       *  Closes catalog @a c by calling do_close(c).
+       *
+       *  @param  c  The catalog to close.
+      */
       void 
       close(catalog __c) const
       { return this->do_close(__c); }
 
     protected:
+      /// Destructor.
       virtual 
       ~messages();
 
+      /*
+       *  @brief  Open a message catalog.
+       *
+       *  This function opens and returns a handle to a message catalog in an
+       *  implementation-defined manner.  This function is a hook for derived
+       *  classes to change the value returned.
+       *
+       *  @param  s  The catalog to open.
+       *  @param  loc  Locale to use for character set conversions.
+       *  @return  Handle to the opened catalog, value < 0 if open failed.
+      */
       virtual catalog 
       do_open(const basic_string<char>&, const locale&) const;
 
+      /*
+       *  @brief  Look up a string in a message catalog.
+       *
+       *  This function retrieves and returns a message from a catalog in an
+       *  implementation-defined manner.  This function is a hook for derived
+       *  classes to change the value returned.
+       *
+       *  For gnu, @a set and @a msgid are ignored.  Returns gettext(s).
+       *  For default, returns s. For ieee, returns catgets(c,set,msgid,s).
+       *
+       *  @param  c  The catalog to access.
+       *  @param  set  Implementation-defined.
+       *  @param  msgid  Implementation-defined.
+       *  @param  s  Default return value if retrieval fails.
+       *  @return  Retrieved message or @a s if get fails.
+      */
       virtual string_type  
       do_get(catalog, int, int, const string_type& __dfault) const;
 
+      /*
+       *  @brief  Close a message catalog.
+       *
+       *  @param  c  The catalog to close.
+      */
       virtual void    
       do_close(catalog) const;
 
diff --git a/libstdc++-v3/include/bits/locale_facets.tcc b/libstdc++-v3/include/bits/locale_facets.tcc
index 0840ba1..4a6d532 100644
--- a/libstdc++-v3/include/bits/locale_facets.tcc
+++ b/libstdc++-v3/include/bits/locale_facets.tcc
@@ -1551,6 +1551,10 @@ namespace std
     time_get<_CharT, _InIter>::do_date_order() const
     { return time_base::no_order; }
 
+  // Recursively expand a strftime format string and parse it.  Starts w/ %x
+  // and %X from do_get_time() and do_get_date(), which translate to a more
+  // specific string, which may contain yet more strings.  I.e. %x => %r =>
+  // %H:%M:%S => extracted characters.
   template<typename _CharT, typename _InIter>
     void
     time_get<_CharT, _InIter>::