--- trunk/OOPSE-2.0/src/utils/next_combination.hpp	2004/10/28 21:11:12	1678
+++ trunk/OOPSE-2.0/src/utils/next_combination.hpp	2004/10/28 22:26:32	1681
@@ -24,7 +24,7 @@
  */
 
 /**
- * @file GenerateCombination.hpp
+ * @file next_combination.hpp
  * @author    tlin
  * @date  10/27/2004
  * @version 1.0
@@ -39,11 +39,9 @@ namespace oopse {
 namespace oopse {
 
 /**
- * @fn bool next_combination(IteratorContainer<RandomAccessIterator>& iterContainer,
- *                                           RandomAccessIterator first, RandomAccessIterator last)
  * @brief STL next_permuationtation like combination sequence generator.
  * Given the first and last iterator of a sequence, next_combination iteratively generates all 
- * possible combination.
+ * possible combinations.
  * @return if more combination is availiable, otherwise return false
  * @param iterContainer iterator container
  * @param first the first iterator
@@ -66,6 +64,7 @@ namespace oopse {
  * //1
  * //8
  * //1  8
+ * @endcode
  */
 template<class RandomAccessIterator, template<typename ELEM, typename = std::allocator<ELEM> > class IteratorContainer>
 bool next_combination(IteratorContainer<RandomAccessIterator>& iterContainer, RandomAccessIterator first, RandomAccessIterator last) {
@@ -81,15 +80,15 @@ bool next_combination(IteratorContainer<RandomAccessIt
         iterContainer.insert(iterContainer.end(), first);
         return true;
     } else if (*(--i) != endIter){
-        //if the last iterator in iterContainer does not reaches the end, just increment it 
+        //if the last iterator in iterContainer does not reaches the end, just increase its iterator by 1 
         ++(*i);
         return true;
     } else {// the last iterator in iterContainer does not reaches the end
 
         //starts at the end of the sequence and works its way towards the front, looking for two 
         //consecutive members of the sequence where the difference between them is greater 
-        //than one. For example , if the sequence contains 1, 5, 8, 9 (total number is 10, begin
-        //index is 0, therefore 9 is the end index, and the current size is 4). At the end of while
+        //than one. For example , if the sequence contains 1, 5, 8, 9 (total number is 10, first is 0
+        //and the last is 10 (due to STL's half open range)). At the end of while
         //loop, j will point to 5, and i will point to 8, next combination should be 1, 6, 7, 8.
         //If j is less than zero, it means it already reaches the last combination of current size.
         //For instance, sequence may contain 6, 7, 8, 9 at this time, we need to increase the size
@@ -132,16 +131,13 @@ bool next_combination(IteratorContainer<RandomAccessIt
 } //end next_combination
 
 /**
- * @fn bool replaceWildCard(std::vector<std::vector<std::string>::iterator>& cont,
- *                                        std::vector<std::string>& sequence, std::vector<std::string>& result,
- *                                        const std::string& wildCard)
  * @brief iteratively replace the sequence with wild cards
  * @return true if more combination sequence is avaliable, otherwise return true
- * @param cont iterator container, if expect whole series of combination, just pass an empty iterator 
- * container. The user should not modify the iterator container
+ * @param cont iterator container, if expect the whole series of combinations,  pass an empty iterator 
+ * container. The user should not modify this iterator container
  * @param sequence the whole sequence used to generate combination
  * @param result a possible combination sequence which is set on return
- * @wildCard the wild card string. Its value is "X" by default
+ * @param wildCard the wild card string. Its value is "X" by default
  * @note since next_combination never returns an empty sequence, replaceWildCard will not generate 
  * one special combination, which is n identical wild cards (n is equal to the size of the passing sequence)
  * 
@@ -188,7 +184,7 @@ bool replaceWildCard(std::vector<std::vector<std::stri
 
      return hasMoreCombination;
     
-}
+}//end replaceWildCard
 
 } //end namespace oopse
 #endif //UTILS_NEXT_COMBINATION_HPP