We need better documentation for functions with ranges and templates

[John Colvin via Digitalmars-d]

On Tuesday, 15 December 2015 at 14:03:50 UTC, rumbu wrote:
> This is a *good* documentation:
> - "Count" is a better name than "walkLength"; every other 
> programming language will use concepts similar to count, cnt, 
> length, len.

meh, I like walkLength. I hate it when a innocuous looking little 
function does a bunch of expensive work unexpectedly, 
"walkLength" really points out the worst case. Also, it's 
important to be reminded that is might actually iterate your 
range, which the "walk" bit really does, so if it's an inputRange 
then say goodbye to your data.

> - You don't need to understand computer science terms to find 
> out what a function does;

A little nudge to understand some important concepts never hurts. 
It can sometimes get a bit obscure though, or be too 
self-referential (there are probably some non-trivial cycles in 
the required knowledge graph).

> - If you are really interested about more than finding out the 
> number of elements, there is a performance hint in the Remarks 
> section.

Considering that despite the fact my phone can perform billions 
of calculations per second but it still takes >2s to open up a 
text-editor app (on a good day), it seems worthwhile to point out 
performance a little more forcefully than "here's some other 
information if you feel like it".

> - Links are provided to concepts: even the return type (int) 
> has a link.
>
> [ ... ]
>
> On the contrary, the D documentation, introduces a bunch of 
> non-linked concepts, but it tells me that it's possible to 
> perform O(n) evaluations:
> - isInputRange
> - isInfiniteRange
> - hasLength
> - empty
> - popFront

We should definitely have more links.

> There is no indication what happens if the range is undefined 
> in D docs. In fact, inconsistent behavior:
> - it will return 0 in case of null arrays;
> - it will throw AccessViolation for null ranges (or probably 
> segfault on Linux);

Fair point. I'd love it if phobos range functions treated arrays 
100% consistently with custom ranges, but apparently that boat 
sailed off in multiple directions at once long ago...