We need better documentation for functions with ranges and templates

[Jack Stouffer via Digitalmars-d]

On Monday, 14 December 2015 at 20:25:17 UTC, bachmeier wrote:
> On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer 
> wrote:
>
>> If you're trying to use Phobos without knowing what template 
>> constraints and ranges are, you're going to have a bad time.
>
> D is doomed if new users have to understand template 
> constraints and ranges to use the standard library.

C is doomed if you have to understand pointers to use the 
standard library
C++ is doomed if you have to understand templates and iterators 
to use the STL
Rust is doomed if you have to understand borrowing to use the 
standard library
Haskell is doomed if you have to understand functional 
programming to use the standard library
Java is doomed if you have to understand OOP to use the standard 
library

All this is to say that there is a necessary level of overhead to 
use any language. You can't expect to jump into most languages 
without learning new concepts and changing the way you look at 
things. The only languages I know of that doesn't require you to 
change the way you think are scripting languages and Go, and 
that's bitting the latter in the ass.

Also, most of Phobos doesn't use ranges.

> To be honest, I don't know why you should have to understand 
> either of those to test if two arrays have the same length.

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.

>> I'm not sure what else to say here. You can't expect to use 
>> the language to it's fullest without understanding these 
>> features.
>
> There's a difference between using all the features of a 
> language and the documentation of the standard library. The 
> documentation should be accessible to new users of the language.

I disagree. The Phobos documentation is not a tutorial and 
shouldn't act like it. If there are concepts that aren't obvious 
to someone who knows D, for example the fact that you can use 
lambdas in place of string predicates in a lot of Phobos 
functions, then fine, document away. But the function signatures 
require only knowledge that you would gain by reading Ali's book, 
which is called the official tutorial for a reason.

> The only criticism I'd have is that there needs to be a link to 
> intro material on ranges.

There is, look at the top of this page: 
http://dlang.org/phobos/std_algorithm.html