We need better documentation for functions with ranges and templates

Andrei Alexandrescu via Digitalmars-d digitalmars-d at puremagic.com
Mon Dec 14 19:50:06 PST 2015


On 12/14/15 9:34 PM, Steven Schveighoffer wrote:
> 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?

This function (immensely useful, very general) is a very good archetype 
for thinking how to structure documentation properly. One good start 
would be to deconstruct the would-be documentation into components. 
Where do we want to list the overloads? How about the template 
parameters? The constraints? Examples? Free text?

A mock-up of "The Great Page for find()" would be useful.

Andrei




More information about the Digitalmars-d mailing list