We need better documentation for functions with ranges and templates

[Ola Fosheim Grøstad via Digitalmars-d]

On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
> 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?

Maybe just try to write up some examples of what it could look 
like. The full signature could be an expandable section and 
hidden from newbies.

"
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if 
(isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 
&& !isInfinite!Range2);
"

Could be something like this:

"
isSameLength(r1, r2) -> bool
r1,r2 : finite input range
"
with a "+" icon in the margin to see the formal description.