gslice.h (gslice): Document.

2004-02-02  Jerry Quinn  <jlquinn@optonline.net>

	* include/bits/gslice.h (gslice):  Document.
	* include/bits/gslice_array.h (gslice_array):  Document.
	* include/bits/indirect_array (indirect_array):  Document.
	* include/bits/mask_array (mask_array):  Document.
	* include/bits/slice_array.h (slice,slice_array):  Document.
	* include/bits/stl_numeric.h (accumulate, inner_product, partial_sum,
	adjacent_difference):  Document
	* include/std/std_valarray.h (valarray):  Document.

From-SVN: r77153

libstdc++-v3/ChangeLog

+2004-02-02  Jerry Quinn  <jlquinn@optonline.net>
+
+	* include/bits/gslice.h (gslice):  Document.
+	* include/bits/gslice_array.h (gslice_array):  Document.
+	* include/bits/indirect_array (indirect_array):  Document.
+	* include/bits/mask_array (mask_array):  Document.
+	* include/bits/slice_array.h (slice,slice_array):  Document.
+	* include/bits/stl_numeric.h (accumulate, inner_product, partial_sum,
+	adjacent_difference):  Document
+	* include/std/std_valarray.h (valarray):  Document.
+
 2004-02-02  Benjamin Kosnik  <bkoz@redhat.com>
 
         * docs/html/19_diagnostics/howto.html: Move verbose terminate

libstdc++-v3/include/bits/gslice.h

@@ -41,40 +41,80 @@
 
 namespace std {
     
+  /**
+   *  @brief  Class defining multi-dimensional subset of an array.
+   *
+   *  The slice class represents a multi-dimensional subset of an array,
+   *  specified by three parameter sets: start offset, size array, and stride
+   *  array.  The start offset is the index of the first element of the array
+   *  that is part of the subset.  The size and stride array describe each
+   *  dimension of the slice.  Size is the number of elements in that
+   *  dimension, and stride is the distance in the array between successive
+   *  elements in that dimension.  Each dimension's size and stride is taken
+   *  to begin at an array element described by the previous dimension.  The
+   *  size array and stride array must be the same size.
+   *
+   *  For example, if you have offset==3, stride[0]==11, size[1]==3,
+   *  stride[1]==3, then slice[0,0]==array[3], slice[0,1]==array[6],
+   *  slice[0,2]==array[9], slice[1,0]==array[14], slice[1,1]==array[17],
+   *  slice[1,2]==array[20].
+   */
     class gslice
     {
     public:
-        gslice ();
-        gslice (size_t, const valarray<size_t>&, const valarray<size_t>&);
-        // XXX: the IS says the copy-ctor and copy-assignment operators are
-        //      synthetized by the compiler but they are just unsuitable
-        //      for a ref-counted semantic
-        gslice(const gslice&);
-        ~gslice();
-
-        // XXX: See the note above.
-        gslice& operator= (const gslice&);
+      ///  Construct an empty slice.
+      gslice ();
+
+      /**
+       *  @brief  Construct a slice.
+       *
+       *  Constructs a slice with as many dimensions as the length of the @a l
+       *  and @a s arrays.
+       *
+       *  @param  o  Offset in array of first element.
+       *  @param  l  Array of dimension lengths.
+       *  @param  s  Array of dimension strides between array elements.
+       */
+      gslice(size_t, const valarray<size_t>&, const valarray<size_t>&);
+
+      // XXX: the IS says the copy-ctor and copy-assignment operators are
+      //      synthetized by the compiler but they are just unsuitable
+      //      for a ref-counted semantic
+      ///  Copy constructor.
+      gslice(const gslice&);
+
+      ///  Destructor.
+      ~gslice();
+
+      // XXX: See the note above.
+      ///  Assignment operator.
+      gslice& operator=(const gslice&);
         
-        size_t           start () const;
-        valarray<size_t> size () const;
-        valarray<size_t> stride () const;
+      ///  Return array offset of first slice element.
+      size_t           start() const;
+
+      ///  Return array of sizes of slice dimensions.
+      valarray<size_t> size() const;
+
+      ///  Return array of array strides for each dimension.
+      valarray<size_t> stride() const;
         
     private:
-        struct _Indexer {
-            size_t _M_count;
-            size_t _M_start;
-            valarray<size_t> _M_size;
-            valarray<size_t> _M_stride;
-            valarray<size_t> _M_index;
-            _Indexer(size_t, const valarray<size_t>&,
-                     const valarray<size_t>&);
-            void _M_increment_use() { ++_M_count; }
-            size_t _M_decrement_use() { return --_M_count; }
-        };
-
-        _Indexer* _M_index;
+      struct _Indexer {
+	size_t _M_count;
+	size_t _M_start;
+	valarray<size_t> _M_size;
+	valarray<size_t> _M_stride;
+	valarray<size_t> _M_index;
+	_Indexer(size_t, const valarray<size_t>&,
+		 const valarray<size_t>&);
+	void _M_increment_use() { ++_M_count; }
+	size_t _M_decrement_use() { return --_M_count; }
+      };
+
+      _Indexer* _M_index;
         
-        template<typename _Tp> friend class valarray;
+      template<typename _Tp> friend class valarray;
     };
     
     inline size_t

libstdc++-v3/include/bits/gslice_array.h

@@ -41,23 +41,48 @@
 
 namespace std {
 
+  /**
+   *  @brief  Reference to multi-dimensional subset of an array.
+   *
+   *  A gslice_array is a reference to the actual elements of an array
+   *  specified by a gslice.  The way to get a gslice_array is to call
+   *  operator[](gslice) on a valarray.  The returned gslice_array then
+   *  permits carrying operations out on the referenced subset of elements in
+   *  the original valarray.  For example, operator+=(valarray) will add
+   *  values to the subset of elements in the underlying valarray this
+   *  gslice_array refers to.
+   *
+   *  @param  Tp  Element type.
+   */
   template<typename _Tp>
     class gslice_array
     {
     public:
       typedef _Tp value_type;
 
+      ///  Assign slice elements to corresponding elements of @a v.
       void operator=(const valarray<_Tp>&) const;
+      ///  Multiply slice elements by corresponding elements of @a v.
       void operator*=(const valarray<_Tp>&) const;
+      ///  Divide slice elements by corresponding elements of @a v.
       void operator/=(const valarray<_Tp>&) const;
+      ///  Modulo slice elements by corresponding elements of @a v.
       void operator%=(const valarray<_Tp>&) const;
+      ///  Add corresponding elements of @a v to slice elements.
       void operator+=(const valarray<_Tp>&) const;
+      ///  Subtract corresponding elements of @a v from slice elements.
       void operator-=(const valarray<_Tp>&) const;
+      ///  Logical xor slice elements with corresponding elements of @a v.
       void operator^=(const valarray<_Tp>&) const;
+      ///  Logical and slice elements with corresponding elements of @a v.
       void operator&=(const valarray<_Tp>&) const;
+      ///  Logical or slice elements with corresponding elements of @a v.
       void operator|=(const valarray<_Tp>&) const;
+      ///  Left shift slice elements by corresponding elements of @a v.
       void operator<<=(const valarray<_Tp>&) const;
+      ///  Right shift slice elements by corresponding elements of @a v.
       void operator>>=(const valarray<_Tp>&) const;
+      ///  Assign all slice elements to @a t.
       void operator=(const _Tp&) const;
 
       template<class _Dom>
@@ -92,10 +117,14 @@ namespace std {
       gslice_array(_Array<_Tp>, const valarray<size_t>&);
 
       // this constructor needs to be implemented.
+      ///  Copy constructor.  Both slices refer to the same underlying array.
       gslice_array(const gslice_array&);
 
       // not implemented
       gslice_array();
+
+      ///  Assignment operator.  Assigns slice elements to corresponding
+      ///  elements of @a a.
       gslice_array& operator= (const gslice_array&);
     };
 

libstdc++-v3/include/bits/indirect_array.h

@@ -42,66 +42,96 @@
 
 namespace std
 {
+  /**
+   *  @brief  Reference to arbitrary subset of an array.
+   *
+   *  An indirect_array is a reference to the actual elements of an array
+   *  specified by an ordered array of indices.  The way to get an indirect_array is to
+   *  call operator[](valarray<size_t>) on a valarray.  The returned
+   *  indirect_array then permits carrying operations out on the referenced
+   *  subset of elements in the original valarray.
+   *
+   *  For example, if an indirect_array is obtained using the array (4,2,0) as
+   *  an argument, and then assigned to an array containing (1,2,3), then the
+   *  underlying array will have array[0]==3, array[2]==2, and array[4]==1.
+   *
+   *  @param  Tp  Element type.
+   */
   template <class _Tp>
-     class indirect_array
-     {
-     public:
-       typedef _Tp value_type;
-
-       // XXX: This is a proposed resolution for DR-253.
-       indirect_array& operator=(const indirect_array&);
+    class indirect_array
+    {
+    public:
+      typedef _Tp value_type;
+
+      // XXX: This is a proposed resolution for DR-253.
+      ///  Assignment operator.  Assigns elements to corresponding elements
+      ///  of @a a.
+      indirect_array& operator=(const indirect_array&);
        
-       void operator=(const valarray<_Tp>&) const;
-       void operator*=(const valarray<_Tp>&) const;
-       void operator/=(const valarray<_Tp>&) const;
-       void operator%=(const valarray<_Tp>&) const; 
-       void operator+=(const valarray<_Tp>&) const;
-       void operator-=(const valarray<_Tp>&) const;  
-       void operator^=(const valarray<_Tp>&) const;
-       void operator&=(const valarray<_Tp>&) const;
-       void operator|=(const valarray<_Tp>&) const;
-       void operator<<=(const valarray<_Tp>&) const;
-       void operator>>=(const valarray<_Tp>&) const; 
-       void operator= (const _Tp&) const;
-       //    ~indirect_array();
+      ///  Assign slice elements to corresponding elements of @a v.
+      void operator=(const valarray<_Tp>&) const;
+      ///  Multiply slice elements by corresponding elements of @a v.
+      void operator*=(const valarray<_Tp>&) const;
+      ///  Divide slice elements by corresponding elements of @a v.
+      void operator/=(const valarray<_Tp>&) const;
+      ///  Modulo slice elements by corresponding elements of @a v.
+      void operator%=(const valarray<_Tp>&) const; 
+      ///  Add corresponding elements of @a v to slice elements.
+      void operator+=(const valarray<_Tp>&) const;
+      ///  Subtract corresponding elements of @a v from slice elements.
+      void operator-=(const valarray<_Tp>&) const;  
+      ///  Logical xor slice elements with corresponding elements of @a v.
+      void operator^=(const valarray<_Tp>&) const;
+      ///  Logical and slice elements with corresponding elements of @a v.
+      void operator&=(const valarray<_Tp>&) const;
+      ///  Logical or slice elements with corresponding elements of @a v.
+      void operator|=(const valarray<_Tp>&) const;
+      ///  Left shift slice elements by corresponding elements of @a v.
+      void operator<<=(const valarray<_Tp>&) const;
+      ///  Right shift slice elements by corresponding elements of @a v.
+      void operator>>=(const valarray<_Tp>&) const; 
+      ///  Assign all slice elements to @a t.
+      void operator= (const _Tp&) const;
+      //    ~indirect_array();
        
-       template<class _Dom>
-         void operator=(const _Expr<_Dom, _Tp>&) const;
-       template<class _Dom>
-         void operator*=(const _Expr<_Dom, _Tp>&) const;
-       template<class _Dom>
-         void operator/=(const _Expr<_Dom, _Tp>&) const;
-       template<class _Dom>
-         void operator%=(const _Expr<_Dom, _Tp>&) const;
-       template<class _Dom>
-         void operator+=(const _Expr<_Dom, _Tp>&) const;
-       template<class _Dom>
-         void operator-=(const _Expr<_Dom, _Tp>&) const;
-       template<class _Dom>
-         void operator^=(const _Expr<_Dom, _Tp>&) const;
-       template<class _Dom>
-         void operator&=(const _Expr<_Dom, _Tp>&) const;
-       template<class _Dom>
-         void operator|=(const _Expr<_Dom, _Tp>&) const;
-       template<class _Dom>
-         void operator<<=(const _Expr<_Dom, _Tp>&) const;
-       template<class _Dom>
-         void operator>>=(const _Expr<_Dom, _Tp>&) const; 
-
-     private:
-       indirect_array(const indirect_array&);
-       indirect_array(_Array<_Tp>, size_t, _Array<size_t>);
-
-       friend class valarray<_Tp>;
-       friend class gslice_array<_Tp>;
+      template<class _Dom>
+      void operator=(const _Expr<_Dom, _Tp>&) const;
+      template<class _Dom>
+      void operator*=(const _Expr<_Dom, _Tp>&) const;
+      template<class _Dom>
+      void operator/=(const _Expr<_Dom, _Tp>&) const;
+      template<class _Dom>
+      void operator%=(const _Expr<_Dom, _Tp>&) const;
+      template<class _Dom>
+      void operator+=(const _Expr<_Dom, _Tp>&) const;
+      template<class _Dom>
+      void operator-=(const _Expr<_Dom, _Tp>&) const;
+      template<class _Dom>
+      void operator^=(const _Expr<_Dom, _Tp>&) const;
+      template<class _Dom>
+      void operator&=(const _Expr<_Dom, _Tp>&) const;
+      template<class _Dom>
+      void operator|=(const _Expr<_Dom, _Tp>&) const;
+      template<class _Dom>
+      void operator<<=(const _Expr<_Dom, _Tp>&) const;
+      template<class _Dom>
+      void operator>>=(const _Expr<_Dom, _Tp>&) const; 
+
+    private:
+      ///  Copy constructor.  Both slices refer to the same underlying array.
+      indirect_array(const indirect_array&);
+      indirect_array(_Array<_Tp>, size_t, _Array<size_t>);
+
+      friend class valarray<_Tp>;
+      friend class gslice_array<_Tp>;
        
-       const size_t 	 _M_sz;
-       const _Array<size_t> _M_index;
-       const _Array<_Tp> 	 _M_array;
+      const size_t 	 _M_sz;
+      const _Array<size_t> _M_index;
+      const _Array<_Tp> 	 _M_array;
        
-       // not implemented
-       indirect_array();
-     };
+      // not implemented
+      indirect_array();
+    };
 
   template<typename _Tp>
     inline 

libstdc++-v3/include/bits/mask_array.h

@@ -42,6 +42,21 @@
 
 namespace std {
 
+  /**
+   *  @brief  Reference to selected subset of an array.
+   *
+   *  A mask_array is a reference to the actual elements of an array specified
+   *  by a bitmask in the form of an array of bool.  The way to get a
+   *  mask_array is to call operator[](valarray<bool>) on a valarray.  The
+   *  returned mask_array then permits carrying operations out on the
+   *  referenced subset of elements in the original valarray.
+   *
+   *  For example, if a mask_array is obtained using the array (false, true,
+   *  false, true) as an argument, the mask array has two elements referring
+   *  to array[1] and array[3] in the underlying array.
+   *
+   *  @param  Tp  Element type.
+   */
   template <class _Tp> 
     class mask_array
     { 
@@ -49,16 +64,27 @@ namespace std {
       typedef _Tp value_type;
     
       void operator=(const valarray<_Tp>&) const;
+      ///  Multiply slice elements by corresponding elements of @a v.
       void operator*=(const valarray<_Tp>&) const;
+      ///  Divide slice elements by corresponding elements of @a v.
       void operator/=(const valarray<_Tp>&) const;
-      void operator%=(const valarray<_Tp>&) const;
-      void operator+=(const valarray<_Tp>&) const; 
-      void operator-=(const valarray<_Tp>&) const;
-      void operator^=(const valarray<_Tp>&) const;  
+      ///  Modulo slice elements by corresponding elements of @a v.
+      void operator%=(const valarray<_Tp>&) const; 
+      ///  Add corresponding elements of @a v to slice elements.
+      void operator+=(const valarray<_Tp>&) const;
+      ///  Subtract corresponding elements of @a v from slice elements.
+      void operator-=(const valarray<_Tp>&) const;  
+      ///  Logical xor slice elements with corresponding elements of @a v.
+      void operator^=(const valarray<_Tp>&) const;
+      ///  Logical and slice elements with corresponding elements of @a v.
       void operator&=(const valarray<_Tp>&) const;
+      ///  Logical or slice elements with corresponding elements of @a v.
       void operator|=(const valarray<_Tp>&) const;
-      void operator<<=(const valarray<_Tp>&) const;  
+      ///  Left shift slice elements by corresponding elements of @a v.
+      void operator<<=(const valarray<_Tp>&) const;
+      ///  Right shift slice elements by corresponding elements of @a v.
       void operator>>=(const valarray<_Tp>&) const; 
+      ///  Assign all slice elements to @a t.
       void operator=(const _Tp&) const;
     
         //        ~mask_array ();
@@ -94,10 +120,14 @@ namespace std {
       const _Array<bool> _M_mask;
       const _Array<_Tp>   _M_array;
       
+      ///  Copy constructor.  Both slices refer to the same underlying array.
       mask_array (const mask_array&);
       
       // not implemented
       mask_array();
+
+      ///  Assignment operator.  Assigns elements to corresponding elements
+      ///  of @a a.
       mask_array& operator=(const mask_array&);
     };
 

libstdc++-v3/include/bits/slice_array.h

@@ -41,14 +41,39 @@
 
 namespace std
 {
+  /**
+   *  @brief  Class defining one-dimensional subset of an array.
+   *
+   *  The slice class represents a one-dimensional subset of an array,
+   *  specified by three parameters: start offset, size, and stride.  The
+   *  start offset is the index of the first element of the array that is part
+   *  of the subset.  The size is the total number of elements in the subset.
+   *  Stride is the distance between each successive array element to include
+   *  in the subset.
+   *
+   *  For example, with an array of size 10, and a slice with offset 1, size 3
+   *  and stride 2, the subset consists of array elements 1, 3, and 5.
+   */
   class slice
   {
   public:
+    ///  Construct an empty slice.
     slice();
+
+    /**
+     *  @brief  Construct a slice.
+     *
+     *  @param  o  Offset in array of first element.
+     *  @param  d  Number of elements in slice.
+     *  @param  s  Stride between array elements.
+     */
     slice(size_t, size_t, size_t);
     
+    ///  Return array offset of first slice element.
     size_t start() const;
+    ///  Return size of slice.
     size_t size() const;
+    ///  Return array stride of slice.
     size_t stride() const;
     
   private:
@@ -78,6 +103,19 @@ namespace std
   slice::stride() const
   { return _M_st; }
 
+  /**
+   *  @brief  Reference to one-dimensional subset of an array.
+   *
+   *  A slice_array is a reference to the actual elements of an array
+   *  specified by a slice.  The way to get a slice_array is to call
+   *  operator[](slice) on a valarray.  The returned slice_array then permits
+   *  carrying operations out on the referenced subset of elements in the
+   *  original valarray.  For example, operator+=(valarray) will add values
+   *  to the subset of elements in the underlying valarray this slice_array
+   *  refers to.
+   *
+   *  @param  Tp  Element type.
+   */
   template<typename _Tp>
     class slice_array
     {
@@ -85,22 +123,37 @@ namespace std
       typedef _Tp value_type;
 
       // This constructor is implemented since we need to return a value.
+      ///  Copy constructor.  Both slices refer to the same underlying array.
       slice_array(const slice_array&);
 
       // This operator must be public.  See DR-253.
+      ///  Assignment operator.  Assigns slice elements to corresponding
+      ///  elements of @a a.
       slice_array& operator=(const slice_array&);
 
+      ///  Assign slice elements to corresponding elements of @a v.
       void operator=(const valarray<_Tp>&) const;
+      ///  Multiply slice elements by corresponding elements of @a v.
       void operator*=(const valarray<_Tp>&) const;
+      ///  Divide slice elements by corresponding elements of @a v.
       void operator/=(const valarray<_Tp>&) const;
+      ///  Modulo slice elements by corresponding elements of @a v.
       void operator%=(const valarray<_Tp>&) const;
+      ///  Add corresponding elements of @a v to slice elements.
       void operator+=(const valarray<_Tp>&) const;
+      ///  Subtract corresponding elements of @a v from slice elements.
       void operator-=(const valarray<_Tp>&) const;
+      ///  Logical xor slice elements with corresponding elements of @a v.
       void operator^=(const valarray<_Tp>&) const;
+      ///  Logical and slice elements with corresponding elements of @a v.
       void operator&=(const valarray<_Tp>&) const;
+      ///  Logical or slice elements with corresponding elements of @a v.
       void operator|=(const valarray<_Tp>&) const;
+      ///  Left shift slice elements by corresponding elements of @a v.
       void operator<<=(const valarray<_Tp>&) const;
+      ///  Right shift slice elements by corresponding elements of @a v.
       void operator>>=(const valarray<_Tp>&) const;
+      ///  Assign all slice elements to @a t.
       void operator=(const _Tp &) const;
       //        ~slice_array ();
 

libstdc++-v3/include/bits/stl_numeric.h

@@ -66,6 +66,17 @@
 namespace std
 {
 
+  /**
+   *  @brief  Accumulate values in a range.
+   *
+   *  Accumulates the values in the range [first,last) using operator+().  The
+   *  initial value is @a init.  The values are processed in order.
+   *
+   *  @param  first  Start of range.
+   *  @param  last  End of range.
+   *  @param  init  Starting value to add other values to.
+   *  @return  The final sum.
+   */
   template<typename _InputIterator, typename _Tp>
     _Tp
     accumulate(_InputIterator __first, _InputIterator __last, _Tp __init)
@@ -79,6 +90,19 @@ namespace std
       return __init;
     }
 
+  /**
+   *  @brief  Accumulate values in a range with operation.
+   *
+   *  Accumulates the values in the range [first,last) using the function
+   *  object @a binary_op.  The initial value is @a init.  The values are
+   *  processed in order.
+   *
+   *  @param  first  Start of range.
+   *  @param  last  End of range.
+   *  @param  init  Starting value to add other values to.
+   *  @param  binary_op  Function object to accumulate with.
+   *  @return  The final sum.
+   */
   template<typename _InputIterator, typename _Tp, typename _BinaryOperation>
     _Tp
     accumulate(_InputIterator __first, _InputIterator __last, _Tp __init,
@@ -93,6 +117,20 @@ namespace std
       return __init;
     }
 
+  /**
+   *  @brief  Compute inner product of two ranges.
+   *
+   *  Starting with an initial value of @a init, multiplies successive
+   *  elements from the two ranges and adds each product into the accumulated
+   *  value using operator+().  The values in the ranges are processed in
+   *  order.
+   *
+   *  @param  first1  Start of range 1.
+   *  @param  last1  End of range 1.
+   *  @param  first2  Start of range 2.
+   *  @param  init  Starting value to add other values to.
+   *  @return  The final inner product.
+   */
   template<typename _InputIterator1, typename _InputIterator2, typename _Tp>
     _Tp
     inner_product(_InputIterator1 __first1, _InputIterator1 __last1,
@@ -108,6 +146,22 @@ namespace std
       return __init;
     }
 
+  /**
+   *  @brief  Compute inner product of two ranges.
+   *
+   *  Starting with an initial value of @a init, applies @a binary_op2 to
+   *  successive elements from the two ranges and accumulates each result into
+   *  the accumulated value using @a binary_op1.  The values in the ranges are
+   *  processed in order.
+   *
+   *  @param  first1  Start of range 1.
+   *  @param  last1  End of range 1.
+   *  @param  first2  Start of range 2.
+   *  @param  init  Starting value to add other values to.
+   *  @param  binary_op1  Function object to accumulate with.
+   *  @param  binary_op2  Function object to apply to pairs of input values.
+   *  @return  The final inner product.
+   */
   template<typename _InputIterator1, typename _InputIterator2, typename _Tp,
 	    typename _BinaryOperation1, typename _BinaryOperation2>
     _Tp
@@ -126,6 +180,20 @@ namespace std
       return __init;
     }
 
+  /**
+   *  @brief  Return list of partial sums
+   *
+   *  Accumulates the values in the range [first,last) using operator+().
+   *  As each successive input value is added into the total, that partial sum
+   *  is written to @a result.  Therefore, the first value in result is the
+   *  first value of the input, the second value in result is the sum of the
+   *  first and second input values, and so on.
+   *
+   *  @param  first  Start of input range.
+   *  @param  last  End of input range.
+   *  @param  result  Output to write sums to.
+   *  @return  Iterator pointing just beyond the values written to result.
+   */
   template<typename _InputIterator, typename _OutputIterator>
     _OutputIterator 
     partial_sum(_InputIterator __first, _InputIterator __last,
@@ -148,6 +216,20 @@ namespace std
       return ++__result;
     }
 
+  /**
+   *  @brief  Return list of partial sums
+   *
+   *  Accumulates the values in the range [first,last) using operator+().
+   *  As each successive input value is added into the total, that partial sum
+   *  is written to @a result.  Therefore, the first value in result is the
+   *  first value of the input, the second value in result is the sum of the
+   *  first and second input values, and so on.
+   *
+   *  @param  first  Start of input range.
+   *  @param  last  End of input range.
+   *  @param  result  Output to write sums to.
+   *  @return  Iterator pointing just beyond the values written to result.
+   */
   template<typename _InputIterator, typename _OutputIterator, typename _BinaryOperation>
     _OutputIterator 
     partial_sum(_InputIterator __first, _InputIterator __last,
@@ -170,6 +252,17 @@ namespace std
       return ++__result;
     }
 
+  /**
+   *  @brief  Return differences between adjacent values.
+   *
+   *  Computes the difference between adjacent values in the range
+   *  [first,last) using operator-() and writes the result to @a result.
+   *
+   *  @param  first  Start of input range.
+   *  @param  last  End of input range.
+   *  @param  result  Output to write sums to.
+   *  @return  Iterator pointing just beyond the values written to result.
+   */
   template<typename _InputIterator, typename _OutputIterator>
     _OutputIterator
     adjacent_difference(_InputIterator __first,
@@ -193,6 +286,18 @@ namespace std
       return ++__result;
     }
 
+  /**
+   *  @brief  Return differences between adjacent values.
+   *
+   *  Computes the difference between adjacent values in the range
+   *  [first,last) using the function object @a binary_op and writes the
+   *  result to @a result.
+   *
+   *  @param  first  Start of input range.
+   *  @param  last  End of input range.
+   *  @param  result  Output to write sums to.
+   *  @return  Iterator pointing just beyond the values written to result.
+   */
   template<typename _InputIterator, typename _OutputIterator, typename _BinaryOperation>
     _OutputIterator 
     adjacent_difference(_InputIterator __first, _InputIterator __last,