We need better documentation for functions with ranges and templates

[Jack Stouffer via Digitalmars-d]

On Monday, 14 December 2015 at 22:31:33 UTC, bachmeier wrote:
> On Monday, 14 December 2015 at 20:52:15 UTC, Jack Stouffer 
> wrote:
>> You don't: array1.length == array2.length. isSameLength is 
>> designed for comparing input ranges but optimizes down to 
>> length checks if either range has a defined length. If you are 
>> dealing with strings or arrays you don't need this function at 
>> all.
>>
>
> All of the examples that *you wrote* for isSameLength are for 
> arrays and strings.

Yes, they are, because strings and arrays are the most simple 
input ranges. But the fact that you didn't know that arrays have 
a length parameter tells me you tried using the language raw and 
you got confused. I don't know why it's surprising to you that 
trying to use a systems language without reading any tutorials is 
going to end up with you hitting walls when the inevitable 
complexity rears its head.

>> I disagree.
>
> That doesn't make much sense - are those new to the language 
> supposed to learn Phobos by reading the source code?

No you're supposed to learn it by reading the official tutorial 
that is linked on every single page in dlang.org in the sidebar.

> I don't want to debate this.

Then why create the thread in the first place? Did you really 
expect everyone to just accept your idea at face value and there 
wouldn't be no discussion at all?

> If it's the official position that Phobos documentation is 
> written for experienced users of the language, then so be it. 
> I'll have to tell others to use a practical language.

It's not the official position. I'm just a contributor and have 
no power what so ever.