Grouping documentation for overloaded functions

[SVN r23385]

include/boost/algorithm/string/case_conv.hpp

@@ -31,12 +31,15 @@ namespace boost {
         //! Convert to lower case
         /*!
             Each element of the input sequence is converted to lower
-            case. The result is copied to the given output iterator.
+            case. The result is a copy of the input converted to lower case.
+			It is returned as a sequence or copied to an output iterator.
 
             \param Output A output iterator to which the result will be copied
             \param Input An input collection
             \param Loc A locale used for conversion
-            \return An output iterator pointing just after last inserted character
+            \return 
+				An output iterator pointing just after last inserted character or
+				a copy of the input
         */
         template<typename OutputIteratorT, typename CollectionT>
         inline OutputIteratorT 
@@ -55,13 +58,8 @@ namespace boost {
 
         //! Convert to lower case
         /*!
-            Each element of the input sequence is converted to lower
+			\overload
-            case. The result is a copy of the input converted to lower case.
+		*/
-
-            \param Input An input sequence
-            \param Loc a locale used for conversion
-            \return A copy of the input converted to lower case
-        */
         template<typename SequenceT>
         inline SequenceT to_lower_copy( 
             const SequenceT& Input, 
@@ -104,12 +102,15 @@ namespace boost {
         //! Convert to upper case
         /*!
             Each element of the input sequence is converted to upper
-            case. The result is copied to the given output iterator.
+            case. The result is a copy of the input converted to upper case.
+			It is returned as a sequence or copied to an output iterator
 
             \param Output A output iterator to which the result will be copied
             \param Input An input collection
-            \param Loc a locale used for conversion
+            \param Loc A locale used for conversion
-            \return An output iterator pointing just after last inserted character
+            \return 
+				An output iterator pointing just after last inserted character or
+				a copy of the input
         */
         template<typename OutputIteratorT, typename CollectionT>
         inline OutputIteratorT 
@@ -128,13 +129,8 @@ namespace boost {
 
         //! Convert to upper case
         /*!
-            Each element of the input sequence is converted to upper
+			\overload
-            case. The result is a copy if the input converted to upper case.
+		*/
-
-            \param Input An input sequence
-            \param Loc a locale used for conversion
-            \return A copy of the input converted to upper case
-        */
         template<typename SequenceT>
         inline SequenceT to_upper_copy( 
             const SequenceT& Input, 

include/boost/algorithm/string/predicate.hpp

@@ -34,6 +34,8 @@ namespace boost {
         /*!
             This predicate holds when the test collection is a prefix of the Input.
             In other word, if the input starts with the test.
+			When optional predicate is specified, it is used for character-wise
+			comparison.
 
             \param Input An input sequence
             \param Test A test sequence
@@ -69,13 +71,8 @@ namespace boost {
 
         //! 'Starts with' predicate
         /*!
-            This predicate holds when the test container is a prefix of the Input.
+			\overload
-            In other words, if the input starts with the test.
+		*/
-
-            \param Input An input sequence
-            \param Test A test sequence
-            \return A result of the test
-        */
         template<typename Collection1T, typename Collection2T>
         inline bool starts_with( 
             const Collection1T& Input, 
@@ -111,6 +108,9 @@ namespace boost {
         /*!
             This predicate holds when the test container is a suffix of the Input.
             In other word, if the input ends with the test.
+			When optional predicate is specified, it is used for character-wise
+			comparison.
+
 
             \param Input An input sequence
             \param Test A test sequence
@@ -141,12 +141,7 @@ namespace boost {
 
         //! 'Ends with' predicate
         /*!
-            This predicate holds when the test container is a suffix of the Input.
+			\overload
-            In other word, if the input ends with the test.
-
-            \param Input An input sequence
-            \param Test A test sequence
-            \return A result of the test
         */
         template<typename Collection1T, typename Collection2T>
         inline bool ends_with( 
@@ -181,7 +176,9 @@ namespace boost {
         //! 'Contains' predicate
         /*!
             This predicate holds when the test container is contained in the Input.
-            
+            When optional predicate is specified, it is used for character-wise
+			comparison.
+
             \param Input An input sequence
             \param Test A test sequence
             \param Comp An element comparison predicate
@@ -204,12 +201,8 @@ namespace boost {
 
         //! 'Contains' predicate
         /*!
-            This predicate holds when the test container is contained in the Input.
+			\overload
-            
+		*/
-            \param Input An input sequence
-            \param Test A test sequence
-            \return A result of the test
-        */
         template<typename Collection1T, typename Collection2T>
         inline bool contains( 
             const Collection1T& Input, 
@@ -243,11 +236,15 @@ namespace boost {
         /*!
             This predicate holds when the test container is equal to the
             input container i.e. all elements in both containers are same.
-            
+            When optional predicate is specified, it is used for character-wise
+			comparison.
+
             \param Input An input sequence
             \param Test A test sequence
             \param Comp An element comparison predicate
             \return A result of the test
+
+            \note This is two-way version of \c std::equal algorithm
         */
         template<typename Collection1T, typename Collection2T, typename PredicateT>
         inline bool equals( 
@@ -278,14 +275,7 @@ namespace boost {
 
         //! 'Equals' predicate
         /*!
-            This predicate holds when the test container is equal to the
+			\overload
-            input container i.e. all elements in both containers are same.
-            
-            \param Input An input sequence
-            \param Test A test sequence
-            \return A result of the test
-
-            \note This is two-way version of \c std::equal algorithm
         */
         template<typename Collection1T, typename Collection2T>
         inline bool equals( 

include/boost/algorithm/string/trim.hpp

@@ -38,12 +38,15 @@ namespace boost {
         /*!
             Remove all leading spaces from the input. Supplied predicate
             is used to determine which character is a space.
-            The result is copied to the given output iterator.
+			The result is a trimmed copy if the input. It is returned as a sequence 
+			or copied to an output iterator
 
             \param Output A output iterator to which the result will be copied
             \param Input An input collection
             \param IsSpace An unary predicate identifying spaces
-            \return An output iterator pointing just after last inserted character
+            \return 
+				An output iterator pointing just after last inserted character or
+				a copy of the input
         */
         template<typename OutputIteratorT, typename CollectionT, typename PredicateT>
         inline OutputIteratorT trim_left_copy_if( 
@@ -64,14 +67,8 @@ namespace boost {
 
         //! Left trim - parametric
         /*!
-            Remove all leading spaces from the input. Supplied predicate
+			\overload
-            is used to determine which character is a space.
+		*/
-            The result is a trimmed copy if the input
-
-            \param Input An input sequence
-            \param IsSpace An unary predicate identifying spaces
-            \return A trimmed copy if the input
-        */
         template<typename SequenceT, typename PredicateT>
         inline SequenceT trim_left_copy_if(const SequenceT& Input, PredicateT IsSpace)
         {
@@ -86,7 +83,7 @@ namespace boost {
         //! Left trim - parametric
         /*!
             Remove all leading spaces from the input. 
-            The result is a trimmed copy if the input
+            The result is a trimmed copy if the input.
 
             \param Input An input sequence
             \param Loc a locale used for 'space' classification
@@ -143,12 +140,15 @@ namespace boost {
         /*!
             Remove all trailing spaces from the input. Supplied predicate
             is used to determine which character is a space.
-            The result is copied to the given output iterator.
+			The result is a trimmed copy if the input. It is returned as a sequence 
+			or copied to an output iterator
 
             \param Output A output iterator to which the result will be copied
             \param Input An input collection
             \param IsSpace An unary predicate identifying spaces
-            \return An output iterator pointing just after last inserted character
+            \return 
+				An output iterator pointing just after last inserted character or
+				a copy of the input
         */
         template<typename OutputIteratorT, typename CollectionT, typename PredicateT>
         inline OutputIteratorT trim_right_copy_if( 
@@ -169,14 +169,8 @@ namespace boost {
 
         //! Right trim - parametric
         /*!
-            Remove all trailing spaces from the input. Supplied predicate
+			\overload
-            is used to determine which character is a space.
+         */
-            The result is a trimmed copy if the input
-
-            \param Input An input Sequence
-            \param IsSpace An unary predicate identifying spaces
-            \return A trimmed copy if the input
-        */
         template<typename SequenceT, typename PredicateT>
         inline SequenceT trim_right_copy_if(const SequenceT& Input, PredicateT IsSpace)
         {
@@ -252,12 +246,15 @@ namespace boost {
         /*!
             Remove all trailing and leading spaces from the input. 
             Supplied predicate is used to determine which character is a space.
-            The result is copied to the given output iterator.
+			The result is a trimmed copy if the input. It is returned as a sequence 
+			or copied to an output iterator
 
             \param Output A output iterator to which the result will be copied
             \param Input An input collection
             \param IsSpace An unary predicate identifying spaces
-            \return An output iterator pointing just after last inserted character
+            \return 
+				An output iterator pointing just after last inserted character or
+				a copy of the input
         */
         template<typename OutputIteratorT, typename CollectionT, typename PredicateT>
         inline OutputIteratorT trim_copy_if( 
@@ -284,14 +281,8 @@ namespace boost {
 
         //! Trim - parametric
         /*!
-            Remove all leading and trailing spaces from the input. 
+			\overload
-            Supplied predicate is used to determine which character is a space.
+         */
-            The result is a trimmed copy if the input
-
-            \param Input An input sequence
-            \param IsSpace An unary predicate identifying spaces
-            \return A trimmed copy if the input
-        */
         template<typename SequenceT, typename PredicateT>
         inline SequenceT trim_copy_if(const SequenceT& Input, PredicateT IsSpace)
         {