TODO: Update.

2003-12-20  Jerry Quinn  <jlquinn@optonline.net>

	* docs/doxygen/TODO: Update.
	* include/bits/locale_classes.h (locale, facet, id): Document.
	* include/bits/locale_facets.tcc (has_facet, use_facet): Document.

From-SVN: r74884

4 files changed, 210 insertions, 4 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index e2d1924..3d98c00 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,9 @@
+2003-12-20  Jerry Quinn  <jlquinn@optonline.net>
+
+	* docs/doxygen/TODO: Update.
+	* include/bits/locale_classes.h (locale, facet, id): Document.
+	* include/bits/locale_facets.tcc (has_facet, use_facet): Document.
+
 2003-12-19  Jason Merrill  <jason@redhat.com>
 
 	* config/cpu/cris/atomicity.h: Remove memory clobbers.
diff --git a/libstdc++-v3/docs/doxygen/TODO b/libstdc++-v3/docs/doxygen/TODO
index b32b2b1..d50c65d 100644
--- a/libstdc++-v3/docs/doxygen/TODO
+++ b/libstdc++-v3/docs/doxygen/TODO
@@ -23,7 +23,7 @@ c18             FINISHED, Note A
 c19             Note A
 c20             Note A
 c21             Public functions basic_string done, Note B
-c22             Untouched; see docs/html/22_locale/*
+c22             Most still to do; see docs/html/22_locale/*
 c23             See doxygroups.cc and Note B.  Notes on what invalidates
                 iterators need to be added.
 c24             stl_iterator.h (__normal_iterator, other small TODO bits)
diff --git a/libstdc++-v3/include/bits/locale_classes.h b/libstdc++-v3/include/bits/locale_classes.h
index 5d9722e..87f9e2b 100644
--- a/libstdc++-v3/include/bits/locale_classes.h
+++ b/libstdc++-v3/include/bits/locale_classes.h
@@ -51,10 +51,24 @@
 namespace std
 {
   // 22.1.1 Class locale
+  /**
+   *  @brief  Container class for localization functionality.
+   *
+   *  The locale class is first a class wrapper for C library locales.  It is
+   *  also an extensible container for user-defined localization.  A locale is
+   *  a collection of facets that implement various localization features such
+   *  as money, time, and number printing.
+   *
+   *  Constructing C++ locales does not change the C library locale.
+   *
+   *  This library supports efficient construction and copying of locales
+   *  through a reference counting implementation of the locale class.
+  */
   class locale
   {
   public:
     // Types:
+    /// Definition of locale::category.
     typedef unsigned int 	category;
 
     // Forward decls and friends:
@@ -76,8 +90,18 @@ namespace std
     template<typename _Cache>
       friend struct __use_cache;
    
-    // Category values:
-    // NB: Order must match _S_facet_categories definition in locale.cc
+    //@{
+    /**
+     *  @brief  Category values.
+     *
+     *  The standard category values are none, ctype, numeric, collate, time,
+     *  monetary, and messages.  They form a bitmask that supports union and
+     *  intersection.  The category all is the union of these values.
+     *
+     *  @if maint
+     *  NB: Order must match _S_facet_categories definition in locale.cc
+     *  @endif
+    */
     static const category none		= 0;
     static const category ctype 	= 1L << 0;
     static const category numeric 	= 1L << 1;
@@ -87,51 +111,173 @@ namespace std
     static const category messages 	= 1L << 5;
     static const category all 		= (ctype | numeric | collate |
 				 	   time  | monetary | messages);
+    //@}
 
     // Construct/copy/destroy:
+    
+    /**
+     *  @brief  Default constructor.
+     *
+     *  Constructs a copy of the global locale.  If no locale has been
+     *  explicitly set, this is the "C" locale.
+    */
     locale() throw();
 
+    /**
+     *  @brief  Copy constructor.
+     *
+     *  Constructs a copy of @a other.
+     *
+     *  @param  other  The locale to copy.
+    */
     locale(const locale& __other) throw();
 
+    /**
+     *  @brief  Named locale constructor.
+     *
+     *  Constructs a copy of the named C library locale.
+     *
+     *  @param  s  Name of the locale to construct.
+     *  @throw  std::runtime_error if s is null or an undefined locale.
+    */
     explicit  
     locale(const char* __s);
 
+    /**
+     *  @brief  Construct locale with facets from another locale.
+     *
+     *  Constructs a copy of the locale @a base.  The facets specified by @a
+     *  cat are replaced with those from the locale named by @a s.  If base is
+     *  named, this locale instance will also be named.
+     *
+     *  @param  base  The locale to copy.
+     *  @param  s  Name of the locale to use facets from.
+     *  @param  cat  Set of categories defining the facets to use from s.  
+     *  @throw  std::runtime_error if s is null or an undefined locale.
+    */
     locale(const locale& __base, const char* __s, category __cat);
 
+    /**
+     *  @brief  Construct locale with facets from another locale.
+     *
+     *  Constructs a copy of the locale @a base.  The facets specified by @a
+     *  cat are replaced with those from the locale @a add.  If @a base and @a
+     *  add are named, this locale instance will also be named.
+     *
+     *  @param  base  The locale to copy.
+     *  @param  add  The locale to use facets from.
+     *  @param  cat  Set of categories defining the facets to use from add.
+    */
     locale(const locale& __base, const locale& __add, category __cat);
 
+    /**
+     *  @brief  Construct locale with another facet.
+     *
+     *  Constructs a copy of the locale @a other.  The facet @f is added to
+     *  @other, replacing an existing facet of type Facet if there is one.  If
+     *  @f is null, this locale is a copy of @a other.
+     *
+     *  @param  other  The locale to copy.
+     *  @param  f  The facet to add in.
+    */
     template<typename _Facet>
       locale(const locale& __other, _Facet* __f);
 
+    /// Locale destructor.
     ~locale() throw();
 
-    const locale&  
+    /**
+     *  @brief  Assignment operator.
+     *
+     *  Set this locale to be a copy of @a other.
+     *
+     *  @param  other  The locale to copy.
+     *  @return  A reference to this locale.
+    */
+    const locale&
     operator=(const locale& __other) throw();
 
+    /**
+     *  @brief  Construct locale with another facet.
+     *
+     *  Constructs and returns a new copy of this locale.  Adds or replaces an
+     *  existing facet of type Facet from the locale @a other into the new
+     *  locale.
+     *
+     *  @param  Facet  The facet type to copy from other
+     *  @param  other  The locale to copy from.
+     *  @return  Newly constructed locale.
+     *  @throw  std::runtime_error if other has no facet of type Facet.
+    */
     template<typename _Facet>
       locale  
       combine(const locale& __other) const;
 
     // Locale operations:
+    /**
+     *  @brief  Return locale name.
+     *  @return  Locale name or "*" if unnamed.
+    */
     string 
     name() const;
 
+    /**
+     *  @brief  Locale equality.
+     *
+     *  @param  other  The locale to compare against.
+     *  @return  True if other and this refer to the same locale instance, are
+     *  	 copies, or have the same name.  False otherwise.
+    */
     bool 
     operator==(const locale& __other) const throw ();
 
+    /**
+     *  @brief  Locale inequality.
+     *
+     *  @param  other  The locale to compare against.
+     *  @return  ! (*this == other)
+    */
     inline bool  
     operator!=(const locale& __other) const throw ()
     { return !(this->operator==(__other));  }
 
+    /**
+     *  @brief  Compare two strings according to collate.
+     *
+     *  Template operator to compare two strings using the compare function of
+     *  the collate facet in this locale.  One use is to provide the locale to
+     *  the sort function.  For example, a vector v of strings could be sorted
+     *  according to locale loc by doing:
+     *  @code
+     *  std::sort(v.begin(), v.end(), loc);
+     *  @endcode
+     *
+     *  @param  s1  First string to compare.
+     *  @param  s2  Second string to compare.
+     *  @return  True if collate<Char> facet compares s1 < s2, else false.
+    */
     template<typename _Char, typename _Traits, typename _Alloc>
       bool  
       operator()(const basic_string<_Char, _Traits, _Alloc>& __s1,
 		 const basic_string<_Char, _Traits, _Alloc>& __s2) const;
 
     // Global locale objects:
+    /**
+     *  @brief  Set global locale
+     *
+     *  This function sets the global locale to the argument and returns a
+     *  copy of the previous global locale.  If the argument has a name, it
+     *  will also call std::setlocale(LC_ALL, loc.name()).
+     *
+     *  @param  locale  The new locale to make global.
+     *  @return  Copy of the old global locale.
+    */
     static locale 
     global(const locale&);
 
+    /**
+     *  @brief  Return reference to the "C" locale.
+    */
     static const locale& 
     classic();
 
@@ -185,6 +331,15 @@ namespace std
 
 
   // 22.1.1.1.2  Class locale::facet
+  /**
+   *  @brief  Localization functionality base class.
+   *
+   *  The facet class is the base class for a localization feature, such as
+   *  money, time, and number printing.  It provides common support for facets
+   *  and reference management.
+   *
+   *  Facets may not be copied or assigned.
+  */
   class locale::facet
   {
   private:
@@ -207,10 +362,20 @@ namespace std
     _S_initialize_once();
 
   protected:
+    /**
+     *  @brief  Facet constructor.
+     *
+     *  This is the constructor provided by the standard.  If refs is 0, the
+     *  facet is destroyed when the last referencing locale is destroyed.
+     *  Otherwise the facet will never be destroyed.
+     *
+     *  @param refs  The initial value for reference count.
+    */
     explicit 
     facet(size_t __refs = 0) throw() : _M_refcount(__refs ? 1 : 0)
     { }
 
+    /// Facet destructor.
     virtual 
     ~facet();
 
@@ -257,6 +422,15 @@ namespace std
 
 
   // 22.1.1.1.3 Class locale::id
+  /**
+   *  @brief  Facet ID class.
+   *
+   *  The ID class provides facets with an index used to identify them.
+   *  Every facet class must define a public static member locale::id, or be
+   *  derived from a facet that provides this member, otherwise the facet
+   *  cannot be used in a locale.  The locale::id ensures that each class
+   *  type gets a unique identifier.
+  */
   class locale::id
   {
   private:
@@ -287,6 +461,7 @@ namespace std
   public:
     // NB: This class is always a static data member, and thus can be
     // counted on to be zero-initialized.
+    /// Constructor.
     id() { }
 
     size_t
diff --git a/libstdc++-v3/include/bits/locale_facets.tcc b/libstdc++-v3/include/bits/locale_facets.tcc
index 4dd3be1..b934482 100644
--- a/libstdc++-v3/include/bits/locale_facets.tcc
+++ b/libstdc++-v3/include/bits/locale_facets.tcc
@@ -69,6 +69,18 @@ namespace std
 				__s2.data(), __s2.data() + __s2.length()) < 0);
     }
 
+  /**
+   *  @brief  Test for the presence of a facet.
+   *
+   *  has_facet tests the locale argument for the presence of the facet type
+   *  provided as the template parameter.  Facets derived from the facet
+   *  parameter will also return true.
+   *
+   *  @param  Facet  The facet type to test the presence of.
+   *  @param  locale  The locale to test.
+   *  @return  true if locale contains a facet of type Facet, else false.
+   *  @throw  std::bad_cast if locale doesn't contain the facet.
+  */
   template<typename _Facet>
     inline bool
     has_facet(const locale& __loc) throw()
@@ -78,6 +90,19 @@ namespace std
       return (__i < __loc._M_impl->_M_facets_size && __facets[__i]);
     }
 
+  /**
+   *  @brief  Return a facet.
+   *
+   *  use_facet looks for and returns a reference to a facet of type Facet
+   *  where Facet is the template parameter.  If has_facet(locale) is true,
+   *  there is a suitable facet to return.  It throws std::bad_cast if the
+   *  locale doesn't contain a facet of type Facet.
+   *
+   *  @param  Facet  The facet type to access.
+   *  @param  locale  The locale to use.
+   *  @return  Reference to facet of type Facet.
+   *  @throw  std::bad_cast if locale doesn't contain a facet of type Facet.
+  */
   template<typename _Facet>
     inline const _Facet&
     use_facet(const locale& __loc)