Merge pull request #4985 from wilzbach/other-languages

Provide references to other common names

Author: JackStouffer

std/algorithm/iteration.d

@@ -1384,6 +1384,9 @@ 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.
+
+See_Also: $(LREF chunkBy), which chunks an input range into subranges
+    of equivalent adjacent elements.
 */
 Group!(pred, Range) group(alias pred = "a == b", Range)(Range r)
 {
@@ -1820,6 +1823,8 @@ private struct ChunkByImpl(alias pred, Range)
 
 /**
  * Chunks an input range into subranges of equivalent adjacent elements.
+ * In other languages this is often called `partitionBy`, `groupBy`
+ * or `sliceWhen`.
  *
  * Equivalence is defined by the predicate $(D pred), which can be either
  * binary, which is passed to $(REF binaryFun, std,functional), or unary, which is
@@ -2061,7 +2066,7 @@ version(none) // This requires support for non-equivalence relations
 /**
 Lazily joins a range of ranges with a separator. The separator itself
 is a range. If a separator is not provided, then the ranges are
-joined directly without anything in between them (often called $(D flatten)
+joined directly without anything in between them (often called `flatten`
 in other languages).
 
 Params:

std/algorithm/mutation.d

@@ -2080,12 +2080,11 @@ if (isBidirectionalRange!Range
 /**
 Reverses $(D r) in-place.  Performs $(D r.length / 2) evaluations of $(D
 swap).
-
 Params:
     r = a bidirectional range with swappable elements or a random access range with a length member
 
 See_Also:
-    $(HTTP sgi.com/tech/stl/_reverse.html, STL's _reverse)
+    $(HTTP sgi.com/tech/stl/_reverse.html, STL's _reverse), $(REF retro, std,range) for a lazy reversed range view
 */
 void reverse(Range)(Range r)
 if (isBidirectionalRange!Range && !isRandomAccessRange!Range

std/algorithm/searching.d

@@ -158,6 +158,7 @@ are true.
 Checks if $(I _any) of the elements verifies $(D pred).
 $(D !any) can be used to verify that $(I none) of the elements verify
 $(D pred).
+This is sometimes called `exists` in other languages.
  +/
 template any(alias pred = "a")
 {
@@ -740,6 +741,8 @@ size_t count(alias pred = "true", R)(R haystack)
     $(D startsWith!pred(haystack, needles)) is $(D true). If
     $(D startsWith!pred(haystack, needles)) is not $(D true) for any element in
     $(D haystack), then $(D -1) is returned.
+
+    See_Also: $(REF indexOf, std,string)
   +/
 ptrdiff_t countUntil(alias pred = "a == b", R, Rs...)(R haystack, Rs needles)
     if (isForwardRange!R
@@ -1666,6 +1669,8 @@ pred).
 To _find the last element of a bidirectional $(D haystack) satisfying
 $(D pred), call $(D find!(pred)(retro(haystack))). See $(REF retro, std,range).
 
+`find` behaves similar to `dropWhile` in other languages.
+
 Params:
 
 pred = The predicate for determining if a given element is the one being
@@ -3262,6 +3267,7 @@ unittest
 /**
 Iterates the passed range and returns the minimal element.
 A custom mapping function can be passed to `map`.
+In other languages this is sometimes called `argmin`.
 
 Complexity: O(n)
     Exactly `n - 1` comparisons are needed.
@@ -3353,6 +3359,7 @@ auto minElement(alias map = "a", Range, RangeElementType = ElementType!Range)
 /**
 Iterates the passed range and returns the maximal element.
 A custom mapping function can be passed to `map`.
+In other languages this is sometimes called `argmax`.
 
 Complexity:
     Exactly `n - 1` comparisons are needed.
@@ -4260,10 +4267,11 @@ private void skipAll(alias pred = "a == b", R, Es...)(ref R r, Es es)
 }
 
 /**
-Interval option specifier for $(D until) (below) and others.
+Interval option specifier for `until` (below) and others.
 
 If set to $(D OpenRight.yes), then the interval is open to the right
 (last element is not included).
+This is similar to `takeWhile` in other languages.
 
 Otherwise if set to $(D OpenRight.no), then the interval is closed to the right
 (last element included).
@@ -4410,8 +4418,8 @@ struct Until(alias pred, Range, Sentinel) if (isInputRange!Range)
     import std.algorithm.comparison : equal;
     import std.typecons : No;
     int[] a = [ 1, 2, 4, 7, 7, 2, 4, 7, 3, 5];
-    assert(equal(a.until(7), [1, 2, 4][]));
-    assert(equal(a.until(7, No.openRight), [1, 2, 4, 7][]));
+    assert(equal(a.until(7), [1, 2, 4]));
+    assert(equal(a.until(7, No.openRight), [1, 2, 4, 7]));
 }
 
 @safe unittest
@@ -4423,10 +4431,10 @@ struct Until(alias pred, Range, Sentinel) if (isInputRange!Range)
     static assert(isForwardRange!(typeof(a.until(7))));
     static assert(isForwardRange!(typeof(until!"a == 2"(a, No.openRight))));
 
-    assert(equal(a.until(7), [1, 2, 4][]));
-    assert(equal(a.until([7, 2]), [1, 2, 4, 7][]));
-    assert(equal(a.until(7, No.openRight), [1, 2, 4, 7][]));
-    assert(equal(until!"a == 2"(a, No.openRight), [1, 2][]));
+    assert(equal(a.until(7), [1, 2, 4]));
+    assert(equal(a.until([7, 2]), [1, 2, 4, 7]));
+    assert(equal(a.until(7, No.openRight), [1, 2, 4, 7]));
+    assert(equal(until!"a == 2"(a, No.openRight), [1, 2]));
 }
 
 unittest // bugzilla 13171

std/array.d

@@ -342,13 +342,15 @@ Returns:
 
 /**
 Returns a newly allocated associative _array from a range of key/value tuples.
+
 Params: r = An input range of tuples of keys and values.
 Returns: A newly allocated associative array out of elements of the input
 range, which must be a range of tuples (Key, Value). Returns a null associative
 array reference when given an empty range.
 Duplicates: Associative arrays have unique keys. If r contains duplicate keys,
 then the result will contain the value of the last pair for that key in r.
-See_Also: $(REF Tuple, std,typecons)
+
+See_Also: $(REF Tuple, std,typecons), $(REF zip, std,range)
  */
 
 auto assocArray(Range)(Range r)
@@ -374,7 +376,7 @@ auto assocArray(Range)(Range r)
 {
     import std.range;
     import std.typecons;
-    auto a = assocArray(zip([0, 1, 2], ["a", "b", "c"]));
+    auto a = assocArray(zip([0, 1, 2], ["a", "b", "c"])); // aka zipMap
     assert(is(typeof(a) == string[int]));
     assert(a == [0:"a", 1:"b", 2:"c"]);
 

std/functional.d

@@ -883,6 +883,8 @@ template adjoin(F...) if (F.length > 1)
    function $(D f(x)) that in turn returns $(D
    fun[0](fun[1](...(x)))...). Each function can be a regular
    functions, a delegate, or a string.
+
+   See_Also: $(LREF pipe)
 */
 template compose(fun...)
 {
@@ -936,6 +938,8 @@ template compose(fun...)
 // integer
 int[] a = pipe!(readText, split, map!(to!(int)))("file.txt");
 ----
+
+   See_Also: $(LREF compose)
  */
 alias pipe(fun...) = compose!(Reverse!(fun));
 

std/range/package.d

@@ -205,6 +205,8 @@ Returns:
     A bidirectional range with length if `r` also provides a length. Or,
     if `r` is a random access range, then the return value will be random
     access as well.
+See_Also:
+    $(REF reverse, std,algorithm,mutation) for mutating the source range directly.
  */
 auto retro(Range)(Range r)
 if (isBidirectionalRange!(Unqual!Range))
@@ -837,6 +839,8 @@ Returns:
     An input range at minimum. If all of the ranges in `rs` provide
     a range primitive, the returned range will also provide that range
     primitive.
+
+See_Also: $(LREF only) to chain values to a range
  */
 auto chain(Ranges...)(Ranges rs)
 if (Ranges.length > 0 &&
@@ -2872,17 +2876,27 @@ pure @safe nothrow @nogc unittest
 
 /++
     Convenience function which calls
-    $(D range.$(LREF popFrontN)(n)) and returns $(D range). $(D drop)
-    makes it easier to pop elements from a range
+    `range.$(REF popFrontN, std, range, primitives)(n)) and returns `range`.
+    `drop` makes it easier to pop elements from a range
     and then pass it to another function within a single expression,
-    whereas $(D popFrontN) would require multiple statements.
+    whereas `popFrontN` would require multiple statements.
+
+    `dropBack` provides the same functionality but instead calls
+    `range.$(REF popBackN, std, range, primitives)(n))
 
-    $(D dropBack) provides the same functionality but instead calls
-    $(D range.popBackN(n)).
+    Note: `drop` and `dropBack` will only pop $(I up to)
+    `n` elements but will stop if the range is empty first.
+    In other languages this is sometimes called `skip`.
 
-    Note: $(D drop) and $(D dropBack) will only pop $(I up to)
-    $(D n) elements but will stop if the range is empty first.
+    Params:
+        range = the input range to drop from
+        n = the number of elements to drop
+
+    Returns:
+        `range` with up to `n` elements dropped
 
+    See_Also:
+        $(REF popFront, std, range, primitives),$(REF popBackN, std, range, primitives)
   +/
 R drop(R)(R range, size_t n)
     if (isInputRange!R)
@@ -2969,6 +2983,10 @@ R dropBack(R)(R range, size_t n)
 
     Returns:
         `range` with `n` elements dropped
+
+    See_Also:
+        $(REF popFrontExcatly, std, range, primitives),
+        $(REF popBackExcatly, std, range, primitives)
 +/
 R dropExactly(R)(R range, size_t n)
     if (isInputRange!R)
@@ -7497,6 +7515,14 @@ having to perform dynamic memory allocation.
 As copying the range means copying all elements, it can be
 safely returned from functions. For the same reason, copying
 the returned range may be expensive for a large number of arguments.
+
+Params:
+    values = the values to assemble together
+
+Returns:
+    A `RandomAccessRange` of the assembled values.
+
+See_Also: $(LREF chain) to chain ranges
  */
 auto only(Values...)(auto ref Values values)
     if (!is(CommonType!Values == void) || Values.length == 0)

std/range/primitives.d

@@ -1676,6 +1676,8 @@ auto walkLength(Range)(Range range, const size_t upTo)
 
     $(D popBackN) will behave the same but instead removes elements from
     the back of the (bidirectional) range instead of the front.
+
+    See_Also: $(REF drop, std, range), $(REF dropBack, std, range)
 */
 size_t popFrontN(Range)(ref Range r, size_t n)
     if (isInputRange!Range)
@@ -1807,6 +1809,8 @@ size_t popBackN(Range)(ref Range r, size_t n)
 
     $(D popBackExactly) will behave the same but instead removes elements from
     the back of the (bidirectional) range instead of the front.
+
+    See_Also: $(REF dropExcatly, std, range), $(REF dropBackExactly, std, range)
 */
 void popFrontExactly(Range)(ref Range r, size_t n)
     if (isInputRange!Range)

std/string.d

@@ -369,6 +369,7 @@ alias CaseSensitive = Flag!"caseSensitive";
         If the sequence starting at $(D startIdx) does not represent a well
         formed codepoint, then a $(REF UTFException, std,utf) may be thrown.
 
+    See_Also: $(REF countUntil, std,algorithm,searching)
   +/
 ptrdiff_t indexOf(Range)(Range s, in dchar c,
         in CaseSensitive cs = Yes.caseSensitive)