We need better documentation for functions with ranges and templates

[wobbles via Digitalmars-d]

On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
> It's unanimous, at least among the three of us posting in this 
> Reddit thread:
>
> https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
>
> Something has to be done with the documentation for Phobos 
> functions that involve ranges and templates. The example I gave 
> there is
>
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if 
> (isInputRange!Range1 && isInputRange!Range2 && 
> !isInfinite!Range1 && !isInfinite!Range2);
>
> Unfortunately, that's less ugly than for a lot of functions. In 
> some circumstances, I can see something like that reminding the 
> author of the function about some details, but it can only 
> confuse anyone else.
>
> There is nothing I can do about this. Who makes these 
> decisions? Can we change it to something useful?
>
> Also, I think the documentation for functions involving ranges 
> needs more "for dummies" examples. Too many of those functions 
> leave the reader not having a clue what to do after calling the 
> function. I know how that can be fixed.

I think that most of the problem is simply down to how the 
documentation looks. It's too dense.

I think some whitespace and some color-coding will go a long way 
to making the function signatures better.

bool isSameLength
    (Range1, Range2)                           // a grey color
    (Range1 r1, Range2 r2)                     // a blue
    if (isInputRange!Range1 && isInputRange!Range2 &&
    !isInfinite!Range1 && !isInfinite!Range2);  // same grey color 
as template args, to point out they're working on the template

I think that would make all documentation much easier to glance 
over, and yet easy to read if you need to.

On the examples - more examples can only be better!