We need better documentation for functions with ranges and templates

[bachmeier via Digitalmars-d]

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.