We need better documentation for functions with ranges and templates

[Jack Stouffer via Digitalmars-d]

On Monday, 14 December 2015 at 19:56:29 UTC, dnewbie wrote:
> 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:
>> ...
>
> Take for example C# Docs: 
> https://msdn.microsoft.com/en-us/library/system.collections.arraylist.addrange.aspx
>
> Syntax C#:
>
> public virtual void AddRange(
> 	ICollection c
> )
>
> Parameters:
>     c
>     Type: System.Collections.ICollection
>     The ICollection whose elements should be added to the end 
> of the ArrayList. The collection itself cannot be null, but it 
> can contain elements that are null.
>
> Clean, simple and instructive!

You're not really comparing apples to apples here. isSameLength 
uses generics and type constraints while AddRange uses OOP. 
isSameLength will accept any type that conforms to the concept of 
a finite input range while AddRange will only accept values that 
inherit from or are System.Collections.ICollection. One is 
inherently more complex than the other.

> 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.