stl_algo.h (includes, [...]): Document.

2003-07-15  Jerry Quinn  <jlquinn@optonline.net>

	* include/bits/stl_algo.h (includes, set_union, set_intersection,
        set_difference, set_symmetric_difference, max_element, min_element,
        next_permutation, prev_permutation, find_first_of, find_end):
        Document.
	* include/bits/stl_algobase.h (copy,copy_backward):  Clarify overlap
        restrictions in docs.
	* include/bits/stl_heap.h (push_heap, pop_heap, make_heap, sort_heap):
        Document.
	* docs/doxygen/doxygroups.cc (setoperations):  New group.

From-SVN: r69387

libstdc++-v3/ChangeLog

 2003-07-15  Jerry Quinn  <jlquinn@optonline.net>
 
+	* include/bits/stl_algo.h (includes, set_union, set_intersection,
+        set_difference, set_symmetric_difference, max_element, min_element,
+        next_permutation, prev_permutation, find_first_of, find_end):
+        Document.
+	* include/bits/stl_algobase.h (copy,copy_backward):  Clarify overlap
+        restrictions in docs.
+	* include/bits/stl_heap.h (push_heap, pop_heap, make_heap, sort_heap):
+        Document.
+	* docs/doxygen/doxygroups.cc (setoperations):  New group.
+
+2003-07-15  Jerry Quinn  <jlquinn@optonline.net>
+
         * include/bits/basic_string.h:  Document public functions.
 	* docs/doxygen/TODO:  Update c21 todo.
 

libstdc++-v3/docs/doxygen/doxygroups.cc

@@ -202,6 +202,14 @@ relation.  Rather, it partitions the range.
 */
 
 // // // // // // // // // // // // // // // // // // // // // // // //
+/** @addtogroup setoperations Set operation algorithms
+These algorithms are common set operations performed on sequences that are
+already sorted.
+
+The number of comparisons will be linear.
+*/
+
+// // // // // // // // // // // // // // // // // // // // // // // //
 
 // // // // // // // // // // // // // // // // // // // // // // // //
 /* * @addtogroup groupname description of group

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

@@ -319,8 +319,11 @@ namespace std
    *  This inline function will boil down to a call to @c memmove whenever
    *  possible.  Failing that, if random access iterators are passed, then the
    *  loop count will be known (and therefore a candidate for compiler
-   *  optimizations such as unrolling).  If the input range and the output
-   *  range overlap, then the copy_backward function should be used instead.
+   *  optimizations such as unrolling).  Result may not be contained within
+   *  [first,last); the copy_backward function should be used instead.
+   *
+   *  Note that the end of the output range is permitted to be contained
+   *  within [first,last).
   */
   template<typename _InputIterator, typename _OutputIterator>
     inline _OutputIterator
@@ -443,9 +446,9 @@ namespace std
 
   /**
    *  @brief Copies the range [first,last) into result.
-   *  @param  first  An input iterator.
-   *  @param  last   An input iterator.
-   *  @param  result An output iterator.
+   *  @param  first  A bidirectional iterator.
+   *  @param  last   A bidirectional iterator.
+   *  @param  result A bidirectional iterator.
    *  @return   result - (first - last)
    *
    *  The function has the same effect as copy, but starts at the end of the
@@ -454,6 +457,9 @@ namespace std
    *  possible.  Failing that, if random access iterators are passed, then the
    *  loop count will be known (and therefore a candidate for compiler
    *  optimizations such as unrolling).
+   *
+   *  Result may not be in the range [first,last).  Use copy instead.  Note
+   *  that the start of the output range may overlap [first,last).
   */
   template <typename _BI1, typename _BI2>
     inline _BI2

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

@@ -79,6 +79,15 @@ namespace std
       *(__first + __holeIndex) = __value;
     }
 
+  /**
+   *  @brief  Push an element onto a heap.
+   *  @param  first  Start of heap.
+   *  @param  last   End of heap + element.
+   *  @ingroup heap
+   *
+   *  This operation pushes the element at last-1 onto the valid heap over the
+   *  range [first,last-1).  After completion, [first,last) is a valid heap.
+  */
   template<typename _RandomAccessIterator>
     inline void 
     push_heap(_RandomAccessIterator __first, _RandomAccessIterator __last)
@@ -112,6 +121,17 @@ namespace std
       *(__first + __holeIndex) = __value;
     }
 
+  /**
+   *  @brief  Push an element onto a heap using comparison functor.
+   *  @param  first  Start of heap.
+   *  @param  last   End of heap + element.
+   *  @param  comp   Comparison functor.
+   *  @ingroup heap
+   *
+   *  This operation pushes the element at last-1 onto the valid heap over the
+   *  range [first,last-1).  After completion, [first,last) is a valid heap.
+   *  Compare operations are performed using comp.
+  */
   template<typename _RandomAccessIterator, typename _Compare>
     inline void 
     push_heap(_RandomAccessIterator __first, _RandomAccessIterator __last,
@@ -161,6 +181,15 @@ namespace std
       std::__adjust_heap(__first, _Distance(0), _Distance(__last - __first), __value);
     }
 
+  /**
+   *  @brief  Pop an element off a heap.
+   *  @param  first  Start of heap.
+   *  @param  last   End of heap.
+   *  @ingroup heap
+   *
+   *  This operation pops the top of the heap.  The elements first and last-1
+   *  are swapped and [first,last-1) is made into a heap.
+  */
   template<typename _RandomAccessIterator>
     inline void
     pop_heap(_RandomAccessIterator __first, _RandomAccessIterator __last)
@@ -208,6 +237,17 @@ namespace std
 			 __value, __comp);
     }
 
+  /**
+   *  @brief  Pop an element off a heap using comparison functor.
+   *  @param  first  Start of heap.
+   *  @param  last   End of heap.
+   *  @param  comp   Comparison functor to use.
+   *  @ingroup heap
+   *
+   *  This operation pops the top of the heap.  The elements first and last-1
+   *  are swapped and [first,last-1) is made into a heap.  Comparisons are
+   *  made using comp.
+  */
   template<typename _RandomAccessIterator, typename _Compare>
     inline void 
     pop_heap(_RandomAccessIterator __first,
@@ -221,6 +261,14 @@ namespace std
       std::__pop_heap(__first, __last - 1, __last - 1, _ValueType(*(__last - 1)), __comp);
     }
 
+  /**
+   *  @brief  Construct a heap over a range.
+   *  @param  first  Start of heap.
+   *  @param  last   End of heap.
+   *  @ingroup heap
+   *
+   *  This operation makes the elements in [first,last) into a heap.
+  */
   template<typename _RandomAccessIterator>
     void 
     make_heap(_RandomAccessIterator __first, _RandomAccessIterator __last)
@@ -246,6 +294,16 @@ namespace std
       }
     }
 
+  /**
+   *  @brief  Construct a heap over a range using comparison functor.
+   *  @param  first  Start of heap.
+   *  @param  last   End of heap.
+   *  @param  comp   Comparison functor to use.
+   *  @ingroup heap
+   *
+   *  This operation makes the elements in [first,last) into a heap.
+   *  Comparisons are made using comp.
+  */
   template<typename _RandomAccessIterator, typename _Compare>
     inline void 
     make_heap(_RandomAccessIterator __first, _RandomAccessIterator __last,
@@ -272,6 +330,14 @@ namespace std
       }
     }
 
+  /**
+   *  @brief  Sort a heap.
+   *  @param  first  Start of heap.
+   *  @param  last   End of heap.
+   *  @ingroup heap
+   *
+   *  This operation sorts the valid heap in the range [first,last).
+  */
   template<typename _RandomAccessIterator>
     void
     sort_heap(_RandomAccessIterator __first, _RandomAccessIterator __last)
@@ -286,6 +352,16 @@ namespace std
 	std::pop_heap(__first, __last--);
     }
 
+  /**
+   *  @brief  Sort a heap using comparison functor.
+   *  @param  first  Start of heap.
+   *  @param  last   End of heap.
+   *  @param  comp   Comparison functor to use.
+   *  @ingroup heap
+   *
+   *  This operation sorts the valid heap in the range [first,last).
+   *  Comparisons are made using comp.
+  */
   template<typename _RandomAccessIterator, typename _Compare>
     void 
     sort_heap(_RandomAccessIterator __first, _RandomAccessIterator __last,