We need better documentation for functions with ranges and templates

[dnewbie via Digitalmars-d]

On Monday, 14 December 2015 at 20:08:20 UTC, Jack Stouffer wrote:
> You're not really comparing apples to apples here

In fact I'm not, but the main focus here was about the simplicity 
of the layout used on the C# doc. You can see others examples 
there easily including templates and generics interface.

>> On the otherhand, imagine a newbie looking:
>>
>> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if 
>> (isInputRange!Range1 && isInputRange!Range2 && 
>> !isInfinite!Range1 && !isInfinite!Range2);
>
> They can look at the examples below and see that the function 
> accepts strings and arrays. And they can look at the parameters 
> section and see that r1 and r2 need to be "finite input range"s 
> if they can't read the function signature.

Yes they can and this isn't hard to understand, but remember 
there are newcomers every day. I think it should be simpler like 
MSDN does:

Syntax:
     bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
Parameters:
     Type r1, r2 : Input range.
     Both r1, r2 : needs to be finite.

I think it's better than currently. But this is my thoughts over 
the problems that my friends encounter with D's docs.

Ron.