Merged revisions 33188-33189,33191-33193,33196,33198,33202-33203,33206,33210,33212,33218-33220,33222,33224-33226,33229-33243,33246,33248-33250,33252,33258-33261,33263,33266,33270,33272-33283,33285,33287-33290,33295-33298,33321,33325-33330,33332-33335,33337-33340,33342,33345,33347,33349-33350,33352-33357,33359-33367,33369-33371,33373,33375-33377,33379-33380,33383-33385,33387-33389,33392-33394,33400-33402,33404-33405,33407-33410,33412-33416,33418-33419,33425-33427,33432,33436-33438,33444,33446,33452-33453,33455-33459,33463-33464,33466-33471,33473-33474,33478,33490,33492,33495-33496,33509-33512,33518-33519,33522-33527,33529-33530,33537,33541,33544,33546,33550,33552-33554,33556,33558,33561-33562,33565,33568,33570,33574,33576,33578-33581,33584-33587,33590,33596,33604-33611,33614-33615,33617-33618,33620-33621 via svnmerge from

https://scummvm.svn.sourceforge.net/svnroot/scummvm/scummvm/trunk
 

svn-id: r33624

1 files changed, 49 insertions, 5 deletions

diff --git a/common/algorithm.h b/common/algorithm.h
index beae34245f..3b6c63d55c 100644
--- a/common/algorithm.h
+++ b/common/algorithm.h
@@ -29,6 +29,11 @@
 
 namespace Common {
 
+/**
+ * Copies data from the range [first, last) to [dst, dst + (last - first)).
+ * It requires the range [dst, dst + (last - first)) to be valid.
+ * It also requires dst not to be in the range [first, last).
+ */
 template<class In, class Out>
 Out copy(In first, In last, Out dst) {
 	while (first != last)
@@ -36,6 +41,13 @@ Out copy(In first, In last, Out dst) {
 	return dst;
 }
 
+/**
+ * Copies data from the range [first, last) to [dst - (last - first), dst).
+ * It requires the range [dst - (last - first), dst) to be valid.
+ * It also requires dst not to be in the range [first, last).
+ * 
+ * Unlike copy copy_backward copies the data from the end to the beginning.
+ */
 template<class In, class Out>
 Out copy_backward(In first, In last, Out dst) {
 	while (first != last)
@@ -43,6 +55,15 @@ Out copy_backward(In first, In last, Out dst) {
 	return dst;
 }
 
+/**
+ * Copies data from the range [first, last) to [dst, dst + (last - first)).
+ * It requires the range [dst, dst + (last - first)) to be valid.
+ * It also requires dst not to be in the range [first, last).
+ *
+ * Unlike copy or copy_backward it does not copy all data. It only copies
+ * a data element when operator() of the op parameter returns true for the
+ * passed data element.
+ */
 template<class In, class Out, class Op>
 Out copy_if(In first, In last, Out dst, Op op) {
 	while (first != last) {
@@ -76,6 +97,9 @@ char *set_to(char *first, char *last, Value val) {
 	return last;
 }
 
+/**
+ * Sets all elements in the range [first, last) to val.
+ */
 template<class In, class Value>
 In set_to(In first, In last, Value val) {
 	while (first != last)
@@ -83,6 +107,10 @@ In set_to(In first, In last, Value val) {
 	return first;
 }
 
+/**
+ * Finds the first data value in the range [first, last) matching v.
+ * For data comperance it uses operator == of the data elements.
+ */
 template<class In, class T>
 In find(In first, In last, const T &v) {
 	while (first != last) {
@@ -93,6 +121,10 @@ In find(In first, In last, const T &v) {
 	return last;
 }
 
+/**
+ * Finds the first data value in the range [first, last) for which
+ * the specified predicate p returns true.
+ */
 template<class In, class Pred>
 In find_if(In first, In last, Pred p) {
 	while (first != last) {
@@ -103,15 +135,22 @@ In find_if(In first, In last, Pred p) {
 	return last;
 }
 
+/**
+ * Applies the function f on all elements of the range [first, last).
+ * The processing order is from beginning to end.
+ */
 template<class In, class Op>
 Op for_each(In first, In last, Op f) {
 	while (first != last) f(*first++);
 	return f;
 }
 
-// Simple sort function, modeled after std::sort.
-// Use it like this:  sort(container.begin(), container.end()).
-// Also work on plain old int arrays etc.
+/**
+ * Simple sort function, modeled after std::sort.
+ * Use it like this: sort(container.begin(), container.end()).
+ * Also works on plain old i.e. int arrays etc. For comperance
+ * operator < is used.
+ */
 template<class T>
 void sort(T first, T last) {
 	if (first == last)
@@ -131,8 +170,13 @@ void sort(T first, T last) {
 	}
 }
 
-// Using this with: Common::Less from common/func.h
-// will give the same results as the function above.
+/**
+ * Simple sort function, modeled after std::sort.
+ * It compares data with the given comparator object comp.
+ *
+ * Note: Using this with: Common::Less from common/func.h
+ * will give the same results as the plain sort function.
+ */
 template<class T, class StrictWeakOrdering>
 void sort(T first, T last, StrictWeakOrdering comp) {
 	if (first == last)