Merge pull request #4312 from wilzbach/public_document_algorithms

std.algorithms: document public methods

Author: burner

std/algorithm/comparison.d

@@ -1168,7 +1168,7 @@ size_t levenshteinDistance(alias equals = (a,b) => a == b, Range1, Range2)
     assert(levenshteinDistance("cat"d, "rat"d) == 1);
 }
 
-// compat overload for alias this strings
+/// ditto
 size_t levenshteinDistance(alias equals = (a,b) => a == b, Range1, Range2)
     (auto ref Range1 s, auto ref Range2 t)
     if (isConvertibleToString!Range1 || isConvertibleToString!Range2)
@@ -1240,7 +1240,7 @@ levenshteinDistanceAndPath(alias equals = (a,b) => a == b, Range1, Range2)
     assert(levenshteinDistance("kitten", "sitting") == 3);
 }
 
-// compat overload for alias this strings
+/// ditto
 Tuple!(size_t, EditOp[])
 levenshteinDistanceAndPath(alias equals = (a,b) => a == b, Range1, Range2)
     (auto ref Range1 s, auto ref Range2 t)

std/algorithm/iteration.d

@@ -1319,7 +1319,34 @@ private struct FilterBidiResult(alias pred, Range)
     }
 }
 
-// group
+/**
+Groups consecutively equivalent elements into a single tuple of the element and
+the number of its repetitions.
+
+Similarly to $(D uniq), $(D group) produces a range that iterates over unique
+consecutive elements of the given range. Each element of this range is a tuple
+of the element and the number of times it is repeated in the original range.
+Equivalence of elements is assessed by using the predicate $(D pred), which
+defaults to $(D "a == b").  The predicate is passed to $(XREF functional,binaryFun),
+and can either accept a string, or any callable that can be executed via
+$(D pred(element, element)).
+
+Params:
+    pred = Binary predicate for determining equivalence of two elements.
+    r = The $(XREF_PACK_NAMED range,primitives,isInputRange,input range) to
+        iterate over.
+
+Returns: A range of elements of type $(D Tuple!(ElementType!R, uint)),
+representing each consecutively unique element and its respective number of
+occurrences in that run.  This will be an input range if $(D R) is an input
+range, and a forward range in all other cases.
+*/
+Group!(pred, Range) group(alias pred = "a == b", Range)(Range r)
+{
+    return typeof(return)(r);
+}
+
+/// ditto
 struct Group(alias pred, R) if (isInputRange!R)
 {
     import std.typecons : Rebindable, tuple, Tuple;
@@ -1344,12 +1371,14 @@ struct Group(alias pred, R) if (isInputRange!R)
     private R _input;
     private Tuple!(MutableE, uint) _current;
 
+    ///
     this(R input)
     {
         _input = input;
         if (!_input.empty) popFront();
     }
 
+    ///
     void popFront()
     {
         if (_input.empty)
@@ -1370,23 +1399,27 @@ struct Group(alias pred, R) if (isInputRange!R)
 
     static if (isInfinite!R)
     {
+        ///
         enum bool empty = false;  // Propagate infiniteness.
     }
     else
     {
+        ///
         @property bool empty()
         {
             return _current[1] == 0;
         }
     }
 
+    ///
     @property auto ref front()
     {
         assert(!empty);
         return _current;
     }
 
     static if (isForwardRange!R) {
+        ///
         @property typeof(this) save() {
             typeof(this) ret = this;
             ret._input = this._input.save;
@@ -1396,33 +1429,6 @@ struct Group(alias pred, R) if (isInputRange!R)
     }
 }
 
-/**
-Groups consecutively equivalent elements into a single tuple of the element and
-the number of its repetitions.
-
-Similarly to $(D uniq), $(D group) produces a range that iterates over unique
-consecutive elements of the given range. Each element of this range is a tuple
-of the element and the number of times it is repeated in the original range.
-Equivalence of elements is assessed by using the predicate $(D pred), which
-defaults to $(D "a == b").  The predicate is passed to $(XREF functional,binaryFun),
-and can either accept a string, or any callable that can be executed via
-$(D pred(element, element)).
-
-Params:
-    pred = Binary predicate for determining equivalence of two elements.
-    r = The $(XREF_PACK_NAMED range,primitives,isInputRange,input range) to
-        iterate over.
-
-Returns: A range of elements of type $(D Tuple!(ElementType!R, uint)),
-representing each consecutively unique element and its respective number of
-occurrences in that run.  This will be an input range if $(D R) is an input
-range, and a forward range in all other cases.
-*/
-Group!(pred, Range) group(alias pred = "a == b", Range)(Range r)
-{
-    return typeof(return)(r);
-}
-
 ///
 @safe unittest
 {
@@ -4874,13 +4880,31 @@ private struct UniqResult(alias pred, Range)
     }
 }
 
-// permutations
+/**
+Lazily computes all _permutations of $(D r) using $(WEB
+en.wikipedia.org/wiki/Heap%27s_algorithm, Heap's algorithm).
+
+Returns:
+A forward range the elements of which are an $(XREF range,
+indexed) view into $(D r).
+
+See_Also:
+$(XREF_PACK algorithm,sorting,nextPermutation).
+*/
+Permutations!Range permutations(Range)(Range r)
+    if (isRandomAccessRange!Range && hasLength!Range)
+{
+    return typeof(return)(r);
+}
+
+/// ditto
 struct Permutations(Range)
     if (isRandomAccessRange!Range && hasLength!Range)
 {
     size_t[] indices, state;
     Range r;
 
+    ///
     this(Range r)
     {
         import std.range : iota;
@@ -4892,14 +4916,17 @@ struct Permutations(Range)
         empty = r.length == 0;
     }
 
+    ///
     bool empty;
 
+    ///
     @property auto front()
     {
         import std.range : indexed;
         return r.indexed(indices);
     }
 
+    ///
     void popFront()
     {
         void next(int n)
@@ -4928,23 +4955,6 @@ struct Permutations(Range)
     }
 }
 
-/**
-Lazily computes all _permutations of $(D r) using $(WEB
-en.wikipedia.org/wiki/Heap%27s_algorithm, Heap's algorithm).
-
-Returns:
-A forward range the elements of which are an $(XREF range,
-indexed) view into $(D r).
-
-See_Also:
-$(XREF_PACK algorithm,sorting,nextPermutation).
-*/
-Permutations!Range permutations(Range)(Range r)
-    if (isRandomAccessRange!Range && hasLength!Range)
-{
-    return typeof(return)(r);
-}
-
 ///
 unittest
 {

std/algorithm/mutation.d

@@ -1667,7 +1667,7 @@ if (s != SwapStrategy.stable
     return range;
 }
 
-// Ditto
+/// Ditto
 Range remove
 (SwapStrategy s = SwapStrategy.stable, Range, Offset...)
 (Range range, Offset offset)
@@ -2380,8 +2380,9 @@ unittest
     swap(b1, b2);
 }
 
-// Not yet documented
-void swap(T)(ref T lhs, ref T rhs) if (is(typeof(lhs.proxySwap(rhs))))
+/// ditto
+void swap(T)(ref T lhs, ref T rhs)
+    if (is(typeof(lhs.proxySwap(rhs))))
 {
     lhs.proxySwap(rhs);
 }