We need better documentation for functions with ranges and templates

[bachmeier via Digitalmars-d]

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

> 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 wrote that function, it's documentation, and wrote the 
> examples. In the examples, I clearly show that the function can 
> be used with normal arrays and the explaination in the docs of 
> what the function does is drop dead simple to understand.

I don't think you wrote the part I quoted - as far as I know, it 
was generated automatically. The parts that you wrote are really 
good. Other functions should be documented like that. The only 
criticism I'd have is that there needs to be a link to intro 
material on ranges.