We need better documentation for functions with ranges and templates

[landaire via Digitalmars-d]

On Tuesday, 15 December 2015 at 02:39:16 UTC, Steven 
Schveighoffer wrote:
> On 12/14/15 9:34 PM, Steven Schveighoffer wrote:
>>
>> 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).
>
> Heh, looking at the source, I see I was a victim of improper 
> documentation.
>
> There are 2 additional overloads of find that are NOT 
> DOCUMENTED.
>
> It's likely that the 2 overloads vary only by constraints, and 
> that's why they are not documented.
>
> But as a user, again, I shouldn't have to care what the 
> constraints are specifically.
>
> -Steve

I started exploring D a couple of months ago and I was the 
original poster in the reddit thread who sparked this discussion. 
While on the topic of documentation I wanted to quickly put in my 
thoughts about what frustrated me with the documentation:

- I didn't understand the visual hierarchy for templates at 
first. e.g. canFind: 
https://dlang.org/phobos/std_algorithm_searching.html#canFind. I 
don't remember the exact examples but I had to look at the source 
code to understand what this was trying to show me

- Runnable examples would be *so* useful! They're present on the 
homepage, why can't the examples provided in the inline docs be 
runnable as well?

- Linking types, functions, etc. in the function signatures would 
be great *if possible*. e.g.:

bool startsWith(alias pred = "a == b", R1, R2)(R1 doesThisStart, 
R2 withThis) if (isInputRange!R1 && isInputRange!R2 && 
is(typeof(binaryFun!pred(doesThisStart.front, withThis.front)) : 
bool));

Make bool, isInputRange, typeof, and binaryFun all links to their 
definitions. If I don't know what "isInputRange" does, do I 
really have to go spend more time to figure out where it lives?

- Add another line break between overloaded methods! Having no 
separation between lines makes things very difficult to sort out

Here's an imgur album I created to show some suggestions for 
function signatures: http://imgur.com/a/njHKI

- Dead links = compile error when compiling documentation? This 
was annoying when trying to find out more about OutputRanges. The 
only resource I found was on the std.range page in the tee 
definition, and the link was dead: 
http://dlang.org/phobos/std_range.html#.tee

- Link to where the code is implemented in Phobos at the time of 
compilation. e.g. clicking the actual name of "find" could link 
me here: 
https://github.com/D-Programming-Language/phobos/blob/b6a61d9e719a9d680936db44b98fbb5dd28bf6b1/std/algorithm/searching.d#L1498. More than once I found that reading the code was more useful than reading the documentation.

I find that I learn best by reading documentation. Go's 
documentation is phenomenal and it's very easy to follow and 
understand (yes, I realize this is kind of comparing apples to 
oranges in terms of complexity). I don't want to have to have to 
read documentation on understanding the documentation.

I'm currently on winter break from university and would love to 
help contribute some of these changes if people think they're 
useful as well.