We need better documentation for functions with ranges and templates

[Steven Schveighoffer via Digitalmars-d]

On 12/14/15 8:50 PM, tcak wrote:
> Hiding conditionals does not seem like to be solution. Here is my idea:
>
> Show the function:
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
>
> Then show the conditions separately:
> if(
>    isInputRange!Range1 &&
>    isInputRange!Range2 &&
>    !isInfinite!Range1 &&
>    !isInfinite!Range2
> )

Here are all the overloads of find (each with differing documentation):

InputRange find(alias pred = "a == b", InputRange, Element)(InputRange 
haystack, Element needle) if (isInputRange!InputRange && 
is(typeof(binaryFun!pred(haystack.front, needle)) : bool));
InputRange find(alias pred, InputRange)(InputRange haystack) if 
(isInputRange!InputRange);
R1 find(alias pred = "a == b", R1, R2)(R1 haystack, R2 needle) if 
(isForwardRange!R1 && isForwardRange!R2 && 
is(typeof(binaryFun!pred(haystack.front, needle.front)) : bool) && 
!isRandomAccessRange!R1);
Tuple!(Range, size_t) find(alias pred = "a == b", Range, 
Ranges...)(Range haystack, Ranges needles) if (Ranges.length > 1 && 
is(typeof(startsWith!pred(haystack, needles))));
Range1 find(Range1, alias pred, Range2)(Range1 haystack, 
BoyerMooreFinder!(pred, Range2) needle);

If you can decipher this into what find actually will accept, then you 
have more patience than me. I think what I wanted (it's difficult to 
remember) is whether I could pass in a subrange for find to search for 
as the needle. It appears to reject cases where the haystack is a random 
access range and the needle is a range (but it does work).

My take is that the user only needs to know that if he wants to find a 
needle in a haystack, he does:

auto result = find(haystack, needle [, needle2, ...]);

Find will handle just about any call you can think of. How can the docs 
just say this concisely?

-Steve