howto.html: Add anchor name.

2001-09-25  Phil Edwards  <pme@gcc.gnu.org>

	* docs/html/20_util/howto.html:  Add anchor name.
	* docs/html/23_containers/howto.html:  Line wrapping, another link.
	* docs/html/25_algorithms/howto.html:  Another note.

	* docs/html/ext/howto.html:  Link to SGI extensions.  List DRs and
	link to them...
	* docs/html/ext/lwg-active.html:  ...in this new file (from R19),
	* docs/html/ext/lwg-defects.html:  and this new file (from R19).
	* docs/html/ext/sgiexts.html:  New file.  Mention SGI extensions
	carried over to libstdc++-v3.
	* docs/html/faq/index.html:  Link to SGI extensions.  Mention the
	"missing .." pseudobug.
	* docs/html/faq/index.txt:  Regenerate.

	* include/bits/ios_base.h:  DR-related comment cleanup.
	* include/bits/istream.tcc:  Likewise.
	* include/bits/locale_facets.h:  Likewise.
	* include/bits/locale_facets.tcc:  Likewise.
	* include/bits/ostream.tcc:  Likewise.
	* include/bits/std_bitset.h:  Likewise.
	* include/bits/std_iosfwd.h:  Likewise.
	* include/bits/std_istream.h:  Likewise.
	* include/bits/std_ostream.h:  Likewise.
	* include/bits/std_streambuf.h:  Likewise.
	* include/bits/stl_pair.h:  Likewise.
	* include/bits/streambuf_iterator.h:  Likewise.

	* include/bits/std_map.h:  Remove unused header inclusion guard
	_CPP_BITS_STL_TREE_H from around bits/stl_tree.h.
	* include/bits/std_set.h:  Likewise.

	* include/bits/stl_function.h:  Doxygen markup.
	* docs/doxygen/doxygroups.cc:  New file, specifying module grouping.
	* libsupc++/typeinfo:  Doxygen markup tweak.

From-SVN: r45816

15 files changed, 360 insertions, 78 deletions

diff --git a/libstdc++-v3/include/bits/ios_base.h b/libstdc++-v3/include/bits/ios_base.h
index 381e1cb..b2b8da0 100644
--- a/libstdc++-v3/include/bits/ios_base.h
+++ b/libstdc++-v3/include/bits/ios_base.h
@@ -146,7 +146,7 @@ namespace std
     {
     public:
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-      // Can't do exception(_msg) as defined in 27.4.2.1.1
+      //48.  Use of non-existent exception constructor
       explicit 
       failure(const string& __str) throw();
 
@@ -397,6 +397,7 @@ namespace std
     ios_base();
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
+  //50.  Copy constructor and assignment operator of ios_base
   private:
     ios_base(const ios_base&);
 
diff --git a/libstdc++-v3/include/bits/istream.tcc b/libstdc++-v3/include/bits/istream.tcc
index a2df71f..e0014ea 100644
--- a/libstdc++-v3/include/bits/istream.tcc
+++ b/libstdc++-v3/include/bits/istream.tcc
@@ -1176,7 +1176,7 @@ namespace std
 	  __in.width(0);
 	}
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-// 2000-02-01 Number to be determined
+//211.  operator>>(istream&, string&) doesn't set failbit
       if (!__extracted)
 	__in.setstate (ios_base::failbit);
 #endif
diff --git a/libstdc++-v3/include/bits/locale_facets.h b/libstdc++-v3/include/bits/locale_facets.h
index b5851bf..9a59d81 100644
--- a/libstdc++-v3/include/bits/locale_facets.h
+++ b/libstdc++-v3/include/bits/locale_facets.h
@@ -580,6 +580,7 @@ namespace std
       { return do_get(__in, __end, __io, __err, __v); }
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
+      //XXX.  What number?
       iter_type 
       get(iter_type __in, iter_type __end, ios_base& __io,
 	  ios_base::iostate& __err, short& __v) const
@@ -661,6 +662,7 @@ namespace std
       do_get(iter_type, iter_type, ios_base&, ios_base::iostate&, bool&) const;
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
+      //XXX.  What number?
       virtual iter_type 
       do_get(iter_type, iter_type, ios_base&, ios_base::iostate&, short&) const;
       virtual iter_type 
diff --git a/libstdc++-v3/include/bits/locale_facets.tcc b/libstdc++-v3/include/bits/locale_facets.tcc
index d853d0d..ec0cf11 100644
--- a/libstdc++-v3/include/bits/locale_facets.tcc
+++ b/libstdc++-v3/include/bits/locale_facets.tcc
@@ -663,6 +663,7 @@ namespace std
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
   // NB: This is an unresolved library defect #17
+  //17.  Bad bool parsing
   template<typename _CharT, typename _InIter>
     _InIter
     num_get<_CharT, _InIter>::
@@ -734,6 +735,7 @@ namespace std
 #endif
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
+  //XXX.  Which number?  Presumably same as in locale_facets.h...
   template<typename _CharT, typename _InIter>
     _InIter
     num_get<_CharT, _InIter>::
diff --git a/libstdc++-v3/include/bits/ostream.tcc b/libstdc++-v3/include/bits/ostream.tcc
index 957622b..3318226 100644
--- a/libstdc++-v3/include/bits/ostream.tcc
+++ b/libstdc++-v3/include/bits/ostream.tcc
@@ -644,6 +644,7 @@ namespace std
       typedef basic_ostream<_CharT, _Traits> __ostream_type;
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
 // 167.  Improper use of traits_type::length()
+// Note that this is only in 'Review' status.
       typedef char_traits<char>		     __ctraits_type;
 #endif
       typename __ostream_type::sentry __cerb(__out);
diff --git a/libstdc++-v3/include/bits/std_bitset.h b/libstdc++-v3/include/bits/std_bitset.h
index ef8649c..e70373f 100644
--- a/libstdc++-v3/include/bits/std_bitset.h
+++ b/libstdc++-v3/include/bits/std_bitset.h
@@ -55,11 +55,6 @@
 // individual bits.  This allows us to specialize _Base_bitset for the
 // important special case where the bitset is only a single word.
 
-// The C++ standard does not define the precise semantics of operator[].
-// In this implementation the const version of operator[] is equivalent
-// to test(), except that it does no range checking.  The non-const version
-// returns a reference to a bit, again without doing any range checking.
-
 
 #include <bits/std_cstddef.h>     // for size_t
 #include <bits/std_cstring.h>     // for memset
@@ -618,6 +613,9 @@ public:
 
   // element access:
   //for b[i];
+  // _GLIBCPP_RESOLVE_LIB_DEFECTS Note that this implementation already
+  // resolves DR 11 (items 1 and 2), but does not do the range-checking
+  // required by that DR's resolution.  -pme
   reference operator[](size_t __pos) { return reference(*this,__pos); }
   bool operator[](size_t __pos) const { return _Unchecked_test(__pos); }
 
diff --git a/libstdc++-v3/include/bits/std_iosfwd.h b/libstdc++-v3/include/bits/std_iosfwd.h
index 8a9b702..03ce3d5 100644
--- a/libstdc++-v3/include/bits/std_iosfwd.h
+++ b/libstdc++-v3/include/bits/std_iosfwd.h
@@ -93,7 +93,7 @@ namespace std
     class ostreambuf_iterator;
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-  // Not included.
+  // Not included.   (??? Apparently no LWG number?)
   class ios_base; 
 #endif
 
diff --git a/libstdc++-v3/include/bits/std_istream.h b/libstdc++-v3/include/bits/std_istream.h
index c4e6a9f..66dabde 100644
--- a/libstdc++-v3/include/bits/std_istream.h
+++ b/libstdc++-v3/include/bits/std_istream.h
@@ -202,7 +202,7 @@ namespace std
 
     private:
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-      // Not defined.
+      // Not defined.  (Side effect of DR 50.)
       __istream_type& 
       operator=(const __istream_type&);
 
diff --git a/libstdc++-v3/include/bits/std_map.h b/libstdc++-v3/include/bits/std_map.h
index 4a60430..5239bd0 100644
--- a/libstdc++-v3/include/bits/std_map.h
+++ b/libstdc++-v3/include/bits/std_map.h
@@ -58,9 +58,7 @@
 
 #pragma GCC system_header
 
-#ifndef _CPP_BITS_STL_TREE_H  
 #include <bits/stl_tree.h>
-#endif
 #include <bits/stl_map.h>
 #include <bits/stl_multimap.h>
 
diff --git a/libstdc++-v3/include/bits/std_ostream.h b/libstdc++-v3/include/bits/std_ostream.h
index e8efb3b..0d00e55 100644
--- a/libstdc++-v3/include/bits/std_ostream.h
+++ b/libstdc++-v3/include/bits/std_ostream.h
@@ -170,7 +170,7 @@ namespace std
 
     private:
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-      // Not defined.
+      // Not defined.  (Side effect of DR 50.)
       __ostream_type& 
       operator=(const __ostream_type&);
 
diff --git a/libstdc++-v3/include/bits/std_set.h b/libstdc++-v3/include/bits/std_set.h
index f60defc..9f3f006 100644
--- a/libstdc++-v3/include/bits/std_set.h
+++ b/libstdc++-v3/include/bits/std_set.h
@@ -58,9 +58,7 @@
 
 #pragma GCC system_header
 
-#ifndef _CPP_BITS_STL_TREE_H  /* XXX is this guard needed? */
 #include <bits/stl_tree.h>
-#endif
 #include <bits/stl_set.h>
 #include <bits/stl_multiset.h>
 
diff --git a/libstdc++-v3/include/bits/std_streambuf.h b/libstdc++-v3/include/bits/std_streambuf.h
index 8cc674d..8975f17 100644
--- a/libstdc++-v3/include/bits/std_streambuf.h
+++ b/libstdc++-v3/include/bits/std_streambuf.h
@@ -513,6 +513,7 @@ namespace std
 #endif
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
+    // Side effect of DR 50.
     private:
       basic_streambuf(const __streambuf_type&);
 
diff --git a/libstdc++-v3/include/bits/stl_function.h b/libstdc++-v3/include/bits/stl_function.h
index c439635..51a939a 100644
--- a/libstdc++-v3/include/bits/stl_function.h
+++ b/libstdc++-v3/include/bits/stl_function.h
@@ -53,8 +53,9 @@
  * purpose.  It is provided "as is" without express or implied warranty.
  */
 
-/* NOTE: This is an internal header file, included by other STL headers.
- *   You should not attempt to use it directly.
+/** @file stl_function.h
+ *  This is an internal header file, included by other STL headers.  You
+ *  should not attempt to use it directly.
  */
 
 #ifndef __SGI_STL_INTERNAL_FUNCTION_H
@@ -62,115 +63,230 @@
 
 namespace std
 {
-
+// 20.3.1 base classes
+/** @defgroup s20_3_1_base Functor Base Classes
+ *  Function objects, or @e functors, are objects with an @c operator()
+ *  defined and accessible.  They can be passed as arguments to algorithm
+ *  templates and used in place of a function pointer.  Not only is the
+ *  resulting expressiveness of the library increased, but the generated
+ *  code can be more efficient than what you might write by hand.  When we
+ *  refer to "functors," then, generally we include function pointers in
+ *  the description as well.
+ *
+ *  Often, functors are only created as temporaries passed to algorithm
+ *  calls, rather than being created as named variables.
+ *
+ *  Two examples taken from the standard itself follow.  To perform a
+ *  by-element addition of two vectors @c a and @c b containing @c double,
+ *  and put the result in @c a, use
+ *  \code
+ *  transform (a.begin(), a.end(), b.begin(), a.begin(), plus<double>());
+ *  \endcode
+ *  To negate every element in @c a, use
+ *  \code
+ *  transform(a.begin(), a.end(), a.begin(), negate<double>());
+ *  \endcode
+ *  The addition and negation functions will be inlined directly.
+ *
+ *  The standard functiors are derived from structs named @c unary_function
+ *  and @c binary_function.  These two classes contain nothing but typedefs,
+ *  to aid in generic (template) programming.  If you write your own
+ *  functors, you might consider doing the same.
+ *
+ *  @{
+*/
+/**
+ *  This is one of the @link s20_3_1_base functor base classes @endlink.
+*/
 template <class _Arg, class _Result>
 struct unary_function {
-  typedef _Arg argument_type;
-  typedef _Result result_type;
+  typedef _Arg argument_type;   ///< @c argument_type is the type of the argument (no surprises here)
+  typedef _Result result_type;  ///< @c result_type is the return type
 };
 
+/**
+ *  This is one of the @link s20_3_1_base functor base classes @endlink.
+*/
 template <class _Arg1, class _Arg2, class _Result>
 struct binary_function {
-  typedef _Arg1 first_argument_type;
-  typedef _Arg2 second_argument_type;
-  typedef _Result result_type;
+  typedef _Arg1 first_argument_type;   ///< the type of the first argument (no surprises here)
+  typedef _Arg2 second_argument_type;  ///< the type of the second argument
+  typedef _Result result_type;         ///< type of the return type
 };      
+/** @}  */
 
+// 20.3.2 arithmetic
+/** @defgroup s20_3_2_arithmetic Arithmetic Classes
+ *  Because basic math often needs to be done during an algorithm, the library
+ *  provides functors for those operations.  See the documentation for
+ *  @link s20_3_1_base the base classes @endlink for examples of their use.
+ *
+ *  @{
+*/
+/// One of the @link s20_3_2_arithmetic math functors @endlink.
 template <class _Tp>
 struct plus : public binary_function<_Tp,_Tp,_Tp> {
   _Tp operator()(const _Tp& __x, const _Tp& __y) const { return __x + __y; }
 };
 
+/// One of the @link s20_3_2_arithmetic math functors @endlink.
 template <class _Tp>
 struct minus : public binary_function<_Tp,_Tp,_Tp> {
   _Tp operator()(const _Tp& __x, const _Tp& __y) const { return __x - __y; }
 };
 
+/// One of the @link s20_3_2_arithmetic math functors @endlink.
 template <class _Tp>
 struct multiplies : public binary_function<_Tp,_Tp,_Tp> {
   _Tp operator()(const _Tp& __x, const _Tp& __y) const { return __x * __y; }
 };
 
+/// One of the @link s20_3_2_arithmetic math functors @endlink.
 template <class _Tp>
 struct divides : public binary_function<_Tp,_Tp,_Tp> {
   _Tp operator()(const _Tp& __x, const _Tp& __y) const { return __x / __y; }
 };
 
-// identity_element (not part of the C++ standard).
-
-template <class _Tp> inline _Tp identity_element(plus<_Tp>) {
-  return _Tp(0);
-}
-template <class _Tp> inline _Tp identity_element(multiplies<_Tp>) {
-  return _Tp(1);
-}
-
+/// One of the @link s20_3_2_arithmetic math functors @endlink.
 template <class _Tp>
 struct modulus : public binary_function<_Tp,_Tp,_Tp> 
 {
   _Tp operator()(const _Tp& __x, const _Tp& __y) const { return __x % __y; }
 };
 
+/// One of the @link s20_3_2_arithmetic math functors @endlink.
 template <class _Tp>
 struct negate : public unary_function<_Tp,_Tp> 
 {
   _Tp operator()(const _Tp& __x) const { return -__x; }
 };
+/** @}  */
 
+/** The @c identity_element functions are not part of the C++ standard; SGI
+ *  provided them as an extension.  Its argument is an operation, and its
+ *  return value is the identity element for that operation.  It is overloaded
+ *  for addition and multiplication, and you can overload it for your own
+ *  nefarious operations.
+ *
+ *  @addtogroup SGIextensions
+ *  @{
+*/
+/// An \link SGIextensions SGI extension \endlink.
+template <class _Tp> inline _Tp identity_element(plus<_Tp>) {
+  return _Tp(0);
+}
+/// An \link SGIextensions SGI extension \endlink.
+template <class _Tp> inline _Tp identity_element(multiplies<_Tp>) {
+  return _Tp(1);
+}
+/** @}  */
+
+// 20.3.3 comparisons
+/** @defgroup s20_3_3_comparisons Comparison Classes
+ *  The library provides six wrapper functors for all the basic comparisons
+ *  in C++, like @c <.
+ *
+ *  @{
+*/
+/// One of the @link s20_3_3_comparisons comparison functors @endlink.
 template <class _Tp>
 struct equal_to : public binary_function<_Tp,_Tp,bool> 
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x == __y; }
 };
 
+/// One of the @link s20_3_3_comparisons comparison functors @endlink.
 template <class _Tp>
 struct not_equal_to : public binary_function<_Tp,_Tp,bool> 
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x != __y; }
 };
 
+/// One of the @link s20_3_3_comparisons comparison functors @endlink.
 template <class _Tp>
 struct greater : public binary_function<_Tp,_Tp,bool> 
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x > __y; }
 };
 
+/// One of the @link s20_3_3_comparisons comparison functors @endlink.
 template <class _Tp>
 struct less : public binary_function<_Tp,_Tp,bool> 
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x < __y; }
 };
 
+/// One of the @link s20_3_3_comparisons comparison functors @endlink.
 template <class _Tp>
 struct greater_equal : public binary_function<_Tp,_Tp,bool>
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x >= __y; }
 };
 
+/// One of the @link s20_3_3_comparisons comparison functors @endlink.
 template <class _Tp>
 struct less_equal : public binary_function<_Tp,_Tp,bool> 
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x <= __y; }
 };
+/** @}  */
 
+// 20.3.4 logical operations
+/** @defgroup s20_3_4_logical Boolean Operations Classes
+ *  Here are wrapper functors for Boolean operations:  @c &&, @c ||, and @c !.
+ *
+ *  @{
+*/
+/// One of the @link s20_3_4_logical Boolean operations functors @endlink.
 template <class _Tp>
 struct logical_and : public binary_function<_Tp,_Tp,bool>
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x && __y; }
 };
 
+/// One of the @link s20_3_4_logical Boolean operations functors @endlink.
 template <class _Tp>
 struct logical_or : public binary_function<_Tp,_Tp,bool>
 {
   bool operator()(const _Tp& __x, const _Tp& __y) const { return __x || __y; }
 };
 
+/// One of the @link s20_3_4_logical Boolean operations functors @endlink.
 template <class _Tp>
 struct logical_not : public unary_function<_Tp,bool>
 {
   bool operator()(const _Tp& __x) const { return !__x; }
 };
-
+/** @}  */
+
+// 20.3.5 negators
+/** @defgroup s20_3_5_negators Negators
+ *  The functions @c not1 and @c not2 each take a predicate functor
+ *  and return an instance of @c unary_negate or
+ *  @c binary_negate, respectively.  These classes are functors whose
+ *  @c operator() performs the stored predicate function and then returns
+ *  the negation of the result.
+ *
+ *  For example, given a vector of integers and a trivial predicate,
+ *  \code
+ *  struct IntGreaterThanThree
+ *    : public std::unary_function<int, bool>
+ *  {
+ *      bool operator() (int x) { return x > 3; }
+ *  };
+ *  
+ *  std::find_if (v.begin(), v.end(), not1(IntGreaterThanThree()));
+ *  \endcode
+ *  The call to @c find_if will locate the first index (i) of @c v for which
+ *  "!(v[i] > 3)" is true.
+ *
+ *  The not1/unary_negate combination works on predicates taking a single
+ *  argument.  The not2/binary_negate combination works on predicates which
+ *  take two arguments.
+ *
+ *  @{
+*/
+/// One of the @link s20_3_5_negators negation functors @endlink.
 template <class _Predicate>
 class unary_negate
   : public unary_function<typename _Predicate::argument_type, bool> {
@@ -183,6 +299,7 @@ public:
   }
 };
 
+/// One of the @link s20_3_5_negators negation functors @endlink.
 template <class _Predicate>
 inline unary_negate<_Predicate> 
 not1(const _Predicate& __pred)
@@ -190,6 +307,7 @@ not1(const _Predicate& __pred)
   return unary_negate<_Predicate>(__pred);
 }
 
+/// One of the @link s20_3_5_negators negation functors @endlink.
 template <class _Predicate> 
 class binary_negate 
   : public binary_function<typename _Predicate::first_argument_type,
@@ -206,13 +324,47 @@ public:
   }
 };
 
+/// One of the @link s20_3_5_negators negation functors @endlink.
 template <class _Predicate>
 inline binary_negate<_Predicate> 
 not2(const _Predicate& __pred)
 {
   return binary_negate<_Predicate>(__pred);
 }
-
+/** @}  */
+
+// 20.3.6 binders
+/** @defgroup s20_3_6_binder Binder Classes
+ *  Binders turn functions/functors with two arguments into functors with
+ *  a single argument, storing an argument to be applied later.  For
+ *  example, an variable @c B of type @c binder1st is constructed from a functor
+ *  @c f and an argument @c x.  Later, B's @c operator() is called with a
+ *  single argument @c y.  The return value is the value of @c f(x,y).
+ *  @c B can be "called" with various arguments (y1, y2, ...) and will in
+ *  turn call @c f(x,y1), @c f(x,y2), ...
+ *
+ *  The function @c bind1st is provided to save some typing.  It takes the
+ *  function and an argument as parameters, and returns an instance of
+ *  @c binder1st.
+ *
+ *  The type @c binder2nd and its creator function @c bind2nd do the same
+ *  thing, but the stored argument is passed as the second parameter instead
+ *  of the first, e.g., @c bind2nd(std::minus<float>,1.3) will create a
+ *  functor whose @c operator() accepts a floating-point number, subtracts
+ *  1.3 from it, and returns the result.  (If @c bind1st had been used,
+ *  the functor would perform "1.3 - x" instead.
+ *
+ *  Creator-wrapper functions like @c bind1st are intended to be used in
+ *  calling algorithms.  Their return values will be temporary objects.
+ *  (The goal is to not require you to type names like
+ *  @c std::binder1st<std::plus<int>> for declaring a variable to hold the
+ *  return value from @c bind1st(std::plus<int>,5).
+ *
+ *  These become more useful when combined with the composition functions.
+ *
+ *  @{
+*/
+/// One of the @link s20_3_6_binder binder functors @endlink.
 template <class _Operation> 
 class binder1st
   : public unary_function<typename _Operation::second_argument_type,
@@ -229,7 +381,7 @@ public:
     return op(value, __x); 
   }
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-  // 109. Missing binders for non-const sequence elements
+  //109.  Missing binders for non-const sequence elements
   typename _Operation::result_type
   operator()(typename _Operation::second_argument_type& __x) const {
     return op(value, __x); 
@@ -237,6 +389,7 @@ public:
 #endif
 };
 
+/// One of the @link s20_3_6_binder binder functors @endlink.
 template <class _Operation, class _Tp>
 inline binder1st<_Operation> 
 bind1st(const _Operation& __fn, const _Tp& __x) 
@@ -245,6 +398,7 @@ bind1st(const _Operation& __fn, const _Tp& __x)
   return binder1st<_Operation>(__fn, _Arg1_type(__x));
 }
 
+/// One of the @link s20_3_6_binder binder functors @endlink.
 template <class _Operation> 
 class binder2nd
   : public unary_function<typename _Operation::first_argument_type,
@@ -261,7 +415,7 @@ public:
     return op(__x, value); 
   }
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
-  // 109. Missing binders for non-const sequence elements
+  //109.  Missing binders for non-const sequence elements
   typename _Operation::result_type
   operator()(typename _Operation::first_argument_type& __x) const {
     return op(__x, value); 
@@ -269,6 +423,7 @@ public:
 #endif
 };
 
+/// One of the @link s20_3_6_binder binder functors @endlink.
 template <class _Operation, class _Tp>
 inline binder2nd<_Operation> 
 bind2nd(const _Operation& __fn, const _Tp& __x) 
@@ -276,9 +431,35 @@ bind2nd(const _Operation& __fn, const _Tp& __x)
   typedef typename _Operation::second_argument_type _Arg2_type;
   return binder2nd<_Operation>(__fn, _Arg2_type(__x));
 }
-
-// unary_compose and binary_compose (extensions, not part of the standard).
-
+/** @}  */
+
+/** As an extension to the binders, SGI provided composition functors and
+ *  wrapper functions to aid in their creation.  The @c unary_compose
+ *  functor is constructed from two functions/functors, @c f and @c g.
+ *  Calling @c operator() with a single argument @c x returns @c f(g(x)).
+ *  The function @c compose1 takes the two functions and constructs a
+ *  @c unary_compose variable for you.
+ *  
+ *  @c binary_compose is constructed from three functors, @c f, @c g1,
+ *  and @c g2.  Its @c operator() returns @c f(g1(x),g2(x)).  The function
+ *  @compose2 takes f, g1, and g2, and constructs the @c binary_compose
+ *  instance for you.  For example, if @c f returns an int, then
+ *  \code
+ *  int answer = (compose2(f,g1,g2))(x);
+ *  \endcode
+ *  is equivalent to
+ *  \code
+ *  int temp1 = g1(x);
+ *  int temp2 = g2(x);
+ *  int answer = f(temp1,temp2);
+ *  \endcode
+ *  But the first form is more compact, and can be passed around as a
+ *  functor to other algorithms.
+ *
+ *  @addtogroup SGIextensions
+ *  @{
+*/
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Operation1, class _Operation2>
 class unary_compose
   : public unary_function<typename _Operation2::argument_type,
@@ -296,6 +477,7 @@ public:
   }
 };
 
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Operation1, class _Operation2>
 inline unary_compose<_Operation1,_Operation2> 
 compose1(const _Operation1& __fn1, const _Operation2& __fn2)
@@ -303,6 +485,7 @@ compose1(const _Operation1& __fn1, const _Operation2& __fn2)
   return unary_compose<_Operation1,_Operation2>(__fn1, __fn2);
 }
 
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Operation1, class _Operation2, class _Operation3>
 class binary_compose
   : public unary_function<typename _Operation2::argument_type,
@@ -321,6 +504,7 @@ public:
   }
 };
 
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Operation1, class _Operation2, class _Operation3>
 inline binary_compose<_Operation1, _Operation2, _Operation3> 
 compose2(const _Operation1& __fn1, const _Operation2& __fn2, 
@@ -329,7 +513,29 @@ compose2(const _Operation1& __fn1, const _Operation2& __fn2,
   return binary_compose<_Operation1,_Operation2,_Operation3>
     (__fn1, __fn2, __fn3);
 }
-
+/** @}  */
+
+// 20.3.7 adaptors pointers functions
+/** @defgroup s20_3_7_adaptors Adaptors for pointers to functions
+ *  The advantage of function objects over pointers to functions is that
+ *  the objects in the standard library declare nested typedefs describing
+ *  their argument and result types with uniform names (e.g., @c result_type
+ *  from the base classes @c unary_function and @c binary_function).
+ *  Sometimes those typedefs are required, not just optional.
+ *
+ *  Adaptors are provided to turn pointers to unary (single-argument) and
+ *  binary (double-argument) functions into function objects.  The long-winded
+ *  functor @c pointer_to_unary_function is constructed with a function
+ *  pointer @c f, and its @c operator() called with argument @c x returns
+ *  @c f(x).  The functor @c pointer_to_binary_function does the same thing,
+ *  but with a double-argument @c f and @c operator().
+ *
+ *  The function @c ptr_fun takes a pointer-to-function @c f and constructs
+ *  an instance of the appropriate functor.
+ *
+ *  @{
+*/
+/// One of the @link s20_3_7_adaptors adaptors for function pointers @endlink.
 template <class _Arg, class _Result>
 class pointer_to_unary_function : public unary_function<_Arg, _Result> {
 protected:
@@ -340,12 +546,14 @@ public:
   _Result operator()(_Arg __x) const { return _M_ptr(__x); }
 };
 
+/// One of the @link s20_3_7_adaptors adaptors for function pointers @endlink.
 template <class _Arg, class _Result>
 inline pointer_to_unary_function<_Arg, _Result> ptr_fun(_Result (*__x)(_Arg))
 {
   return pointer_to_unary_function<_Arg, _Result>(__x);
 }
 
+/// One of the @link s20_3_7_adaptors adaptors for function pointers @endlink.
 template <class _Arg1, class _Arg2, class _Result>
 class pointer_to_binary_function : 
   public binary_function<_Arg1,_Arg2,_Result> {
@@ -360,22 +568,31 @@ public:
     }
 };
 
+/// One of the @link s20_3_7_adaptors adaptors for function pointers @endlink.
 template <class _Arg1, class _Arg2, class _Result>
 inline pointer_to_binary_function<_Arg1,_Arg2,_Result> 
 ptr_fun(_Result (*__x)(_Arg1, _Arg2)) {
   return pointer_to_binary_function<_Arg1,_Arg2,_Result>(__x);
 }
+/** @}  */
 
-// identity is an extensions: it is not part of the standard.
+
+// extension documented next
 template <class _Tp>
 struct _Identity : public unary_function<_Tp,_Tp> {
   _Tp& operator()(_Tp& __x) const { return __x; }
   const _Tp& operator()(const _Tp& __x) const { return __x; }
 };
 
+/** As an extension, SGI provided a functor called @c identity.  When a
+ *  functor is required but no operations are desired, this can be used as a
+ *  pass-through.  Its @c operator() returns its argument unchanged.
+ *
+ *  @addtogroup SGIextensions
+*/
 template <class _Tp> struct identity : public _Identity<_Tp> {};
 
-// select1st and select2nd are extensions: they are not part of the standard.
+// extension documented next
 template <class _Pair>
 struct _Select1st : public unary_function<_Pair, typename _Pair::first_type> {
   typename _Pair::first_type& operator()(_Pair& __x) const {
@@ -397,10 +614,23 @@ struct _Select2nd : public unary_function<_Pair, typename _Pair::second_type>
   }
 };
 
+/** @c select1st and @c select2nd are extensions provided by SGI.  Their
+ *  @c operator()s
+ *  take a @c std::pair as an argument, and return either the first member
+ *  or the second member, respectively.  They can be used (especially with
+ *  the composition functors) to "strip" data from a sequence before
+ *  performing the remainder of an algorithm.
+ *
+ *  @addtogroup SGIextensions
+ *  @{
+*/
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Pair> struct select1st : public _Select1st<_Pair> {};
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Pair> struct select2nd : public _Select2nd<_Pair> {};
+/** @}  */
 
-// project1st and project2nd are extensions: they are not part of the standard
+// extension documented next
 template <class _Arg1, class _Arg2>
 struct _Project1st : public binary_function<_Arg1, _Arg2, _Arg1> {
   _Arg1 operator()(const _Arg1& __x, const _Arg2&) const { return __x; }
@@ -411,16 +641,23 @@ struct _Project2nd : public binary_function<_Arg1, _Arg2, _Arg2> {
   _Arg2 operator()(const _Arg1&, const _Arg2& __y) const { return __y; }
 };
 
+/** The @c operator() of the @c project1st functor takes two arbitrary
+ *  arguments and returns the first one, while @c project2nd returns the
+ *  second one.  They are extensions provided by SGI.
+ *
+ *  @addtogroup SGIextensions
+ *  @{
+*/
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Arg1, class _Arg2> 
 struct project1st : public _Project1st<_Arg1, _Arg2> {};
 
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Arg1, class _Arg2>
 struct project2nd : public _Project2nd<_Arg1, _Arg2> {};
+/** @}  */
 
-// constant_void_fun, constant_unary_fun, and constant_binary_fun are
-// extensions: they are not part of the standard.  (The same, of course,
-// is true of the helper functions constant0, constant1, and constant2.)
-
+// extension documented next
 template <class _Result>
 struct _Constant_void_fun {
   typedef _Result result_type;
@@ -453,12 +690,27 @@ struct _Constant_binary_fun {
   }
 };
 
+/** These three functors are each constructed from a single arbitrary
+ *  variable/value.  Later, their @c operator()s completely ignore any
+ *  arguments passed, and return the stored value.
+ *  - @c constant_void_fun's @c operator() takes no arguments
+ *  - @c constant_unary_fun's @c operator() takes one argument (ignored)
+ *  - @c constant_binary_fun's @c operator() takes two arguments (ignored)
+ *
+ *  The helper creator functions @c constant0, @c constant1, and
+ *  @c constant2 each take a "result" argument and construct variables of
+ *  the appropriate functor type.
+ *
+ *  @addtogroup SGIextensions
+ *  @{
+*/
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Result>
 struct constant_void_fun : public _Constant_void_fun<_Result> {
   constant_void_fun(const _Result& __v) : _Constant_void_fun<_Result>(__v) {}
 };  
 
-
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Result,
           class _Argument = _Result>
 struct constant_unary_fun : public _Constant_unary_fun<_Result, _Argument>
@@ -467,7 +719,7 @@ struct constant_unary_fun : public _Constant_unary_fun<_Result, _Argument>
     : _Constant_unary_fun<_Result, _Argument>(__v) {}
 };
 
-
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Result,
           class _Arg1 = _Result,
           class _Arg2 = _Arg1>
@@ -478,33 +730,42 @@ struct constant_binary_fun
     : _Constant_binary_fun<_Result, _Arg1, _Arg2>(__v) {}
 };
 
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Result>
 inline constant_void_fun<_Result> constant0(const _Result& __val)
 {
   return constant_void_fun<_Result>(__val);
 }
 
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Result>
 inline constant_unary_fun<_Result,_Result> constant1(const _Result& __val)
 {
   return constant_unary_fun<_Result,_Result>(__val);
 }
 
+/// An \link SGIextensions SGI extension \endlink.
 template <class _Result>
 inline constant_binary_fun<_Result,_Result,_Result> 
 constant2(const _Result& __val)
 {
   return constant_binary_fun<_Result,_Result,_Result>(__val);
 }
+/** @}  */
 
-// subtractive_rng is an extension: it is not part of the standard.
-// Note: this code assumes that int is 32 bits.
+/** The @c subtractive_rng class is documented on
+ *  <a href="http://www.sgi.com/tech/stl/">SGI's site</a>.
+ *  Note that this code assumes that @c int is 32 bits.
+ *
+ *  @ingroup SGIextensions
+*/
 class subtractive_rng : public unary_function<unsigned int, unsigned int> {
 private:
   unsigned int _M_table[55];
   size_t _M_index1;
   size_t _M_index2;
 public:
+  /// Returns a number less than the argument.
   unsigned int operator()(unsigned int __limit) {
     _M_index1 = (_M_index1 + 1) % 55;
     _M_index2 = (_M_index2 + 1) % 55;
@@ -531,34 +792,38 @@ public:
     _M_index2 = 31;
   }
 
+  /// Ctor allowing you to initialize the seed.
   subtractive_rng(unsigned int __seed) { _M_initialize(__seed); }
+  /// Default ctor; initializes its state with some number you don't see.
   subtractive_rng() { _M_initialize(161803398u); }
 };
 
 
-// Adaptor function objects: pointers to member functions.
-
-// There are a total of 16 = 2^4 function objects in this family.
-//  (1) Member functions taking no arguments vs member functions taking
-//       one argument.
-//  (2) Call through pointer vs call through reference.
-//  (3) Member function with void return type vs member function with
-//      non-void return type.
-//  (4) Const vs non-const member function.
-
-// Note that choice (3) is nothing more than a workaround: according
-//  to the draft, compilers should handle void and non-void the same way.
-//  This feature is not yet widely implemented, though.  You can only use
-//  member functions returning void if your compiler supports partial
-//  specialization.
-
-// All of this complexity is in the function objects themselves.  You can
-//  ignore it by using the helper function mem_fun and mem_fun_ref,
-//  which create whichever type of adaptor is appropriate.
-//  (mem_fun1 and mem_fun1_ref are no longer part of the C++ standard,
-//  but they are provided for backward compatibility.)
-
-
+// 20.3.8 adaptors pointers members
+/** @defgroup s20_3_8_memadaptors Adaptors for pointers to members
+ *  There are a total of 16 = 2^4 function objects in this family.
+ *   (1) Member functions taking no arguments vs member functions taking
+ *        one argument.
+ *   (2) Call through pointer vs call through reference.
+ *   (3) Member function with void return type vs member function with
+ *       non-void return type.
+ *   (4) Const vs non-const member function.
+ *
+ *  Note that choice (3) is nothing more than a workaround: according
+ *   to the draft, compilers should handle void and non-void the same way.
+ *   This feature is not yet widely implemented, though.  You can only use
+ *   member functions returning void if your compiler supports partial
+ *   specialization.
+ *
+ *  All of this complexity is in the function objects themselves.  You can
+ *   ignore it by using the helper function mem_fun and mem_fun_ref,
+ *   which create whichever type of adaptor is appropriate.
+ *   (mem_fun1 and mem_fun1_ref are no longer part of the C++ standard,
+ *   but they are provided for backward compatibility.)
+ *
+ *  @{
+*/
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Ret, class _Tp>
 class mem_fun_t : public unary_function<_Tp*,_Ret> {
 public:
@@ -568,6 +833,7 @@ private:
   _Ret (_Tp::*_M_f)();
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Ret, class _Tp>
 class const_mem_fun_t : public unary_function<const _Tp*,_Ret> {
 public:
@@ -577,7 +843,7 @@ private:
   _Ret (_Tp::*_M_f)() const;
 };
 
-
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Ret, class _Tp>
 class mem_fun_ref_t : public unary_function<_Tp,_Ret> {
 public:
@@ -587,6 +853,7 @@ private:
   _Ret (_Tp::*_M_f)();
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Ret, class _Tp>
 class const_mem_fun_ref_t : public unary_function<_Tp,_Ret> {
 public:
@@ -596,6 +863,7 @@ private:
   _Ret (_Tp::*_M_f)() const;
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Ret, class _Tp, class _Arg>
 class mem_fun1_t : public binary_function<_Tp*,_Arg,_Ret> {
 public:
@@ -605,6 +873,7 @@ private:
   _Ret (_Tp::*_M_f)(_Arg);
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Ret, class _Tp, class _Arg>
 class const_mem_fun1_t : public binary_function<const _Tp*,_Arg,_Ret> {
 public:
@@ -615,6 +884,7 @@ private:
   _Ret (_Tp::*_M_f)(_Arg) const;
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Ret, class _Tp, class _Arg>
 class mem_fun1_ref_t : public binary_function<_Tp,_Arg,_Ret> {
 public:
@@ -624,6 +894,7 @@ private:
   _Ret (_Tp::*_M_f)(_Arg);
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Ret, class _Tp, class _Arg>
 class const_mem_fun1_ref_t : public binary_function<_Tp,_Arg,_Ret> {
 public:
@@ -633,6 +904,7 @@ private:
   _Ret (_Tp::*_M_f)(_Arg) const;
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Tp>
 class mem_fun_t<void, _Tp> : public unary_function<_Tp*,void> {
 public:
@@ -642,6 +914,7 @@ private:
   void (_Tp::*_M_f)();
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Tp>
 class const_mem_fun_t<void, _Tp> : public unary_function<const _Tp*,void> {
 public:
@@ -651,6 +924,7 @@ private:
   void (_Tp::*_M_f)() const;
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Tp>
 class mem_fun_ref_t<void, _Tp> : public unary_function<_Tp,void> {
 public:
@@ -660,6 +934,7 @@ private:
   void (_Tp::*_M_f)();
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Tp>
 class const_mem_fun_ref_t<void, _Tp> : public unary_function<_Tp,void> {
 public:
@@ -669,6 +944,7 @@ private:
   void (_Tp::*_M_f)() const;
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Tp, class _Arg>
 class mem_fun1_t<void, _Tp, _Arg> : public binary_function<_Tp*,_Arg,void> {
 public:
@@ -678,6 +954,7 @@ private:
   void (_Tp::*_M_f)(_Arg);
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Tp, class _Arg>
 class const_mem_fun1_t<void, _Tp, _Arg> 
   : public binary_function<const _Tp*,_Arg,void> {
@@ -688,6 +965,7 @@ private:
   void (_Tp::*_M_f)(_Arg) const;
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Tp, class _Arg>
 class mem_fun1_ref_t<void, _Tp, _Arg>
   : public binary_function<_Tp,_Arg,void> {
@@ -698,6 +976,7 @@ private:
   void (_Tp::*_M_f)(_Arg);
 };
 
+/// One of the @link s20_3_8_memadaptors adaptors for member pointers @endlink.
 template <class _Tp, class _Arg>
 class const_mem_fun1_ref_t<void, _Tp, _Arg>
   : public binary_function<_Tp,_Arg,void> {
@@ -763,6 +1042,7 @@ template <class _Ret, class _Tp, class _Arg>
 inline const_mem_fun1_ref_t<_Ret,_Tp,_Arg>
 mem_fun1_ref(_Ret (_Tp::*__f)(_Arg) const)
   { return const_mem_fun1_ref_t<_Ret,_Tp,_Arg>(__f); }
+/** @}  */
 
 } // namespace std
 
diff --git a/libstdc++-v3/include/bits/stl_pair.h b/libstdc++-v3/include/bits/stl_pair.h
index b10f965..7bb1dfd 100644
--- a/libstdc++-v3/include/bits/stl_pair.h
+++ b/libstdc++-v3/include/bits/stl_pair.h
@@ -95,7 +95,7 @@ inline bool operator==(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y)
   return __x.first == __y.first && __x.second == __y.second; 
 }
 
-/// ...put link to onlinedocs here...
+/// http://gcc.gnu.org/onlinedocs/libstdc++/20_util/howto.html#pairlt
 template <class _T1, class _T2>
 inline bool operator<(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y)
 { 
@@ -134,8 +134,9 @@ inline bool operator>=(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y) {
  *  @return   A newly-constructed pair<> object of the appropriate type.
  *
  *  The standard requires that the objects be passed by reference-to-const,
- *  but LWG issue #181 says they should be passed by const value.
- */
+ *  but LWG issue #181 says they should be passed by const value.  We follow
+ *  the LWG by default.
+*/
 template <class _T1, class _T2>
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
 //181.  make_pair() unintended behavior
diff --git a/libstdc++-v3/include/bits/streambuf_iterator.h b/libstdc++-v3/include/bits/streambuf_iterator.h
index 96a6bbf..3f946da 100644
--- a/libstdc++-v3/include/bits/streambuf_iterator.h
+++ b/libstdc++-v3/include/bits/streambuf_iterator.h
@@ -173,7 +173,7 @@ namespace std
 
 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
       // 110 istreambuf_iterator::equal not const
-      // NB: there is also number 111 pending on this function.
+      // NB: there is also number 111 (NAD, Future) pending on this function.
       bool 
       equal(const istreambuf_iterator& __b) const
       {