We need better documentation for functions with ranges and templates

[Joakim 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. 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 agree.  I was just debugging one of the phobos tests on 
Android/ARM and I couldn't make head nor tails of what the 
function was supposed to do, after a couple minutes' skim:

http://dlang.org/phobos/std_algorithm_sorting.html#nextEvenPermutation

That may be an obscure function that requires technical knowledge 
to use, but any function should first have a layman's 
description, in case the layman might want to use it.  Template 
constraints and ranges in the Phobos docs definitely suffer from 
this.  Saying that users should always read the relevant sections 
of Ali's book first is not going to work, as most users don't 
RTFM.

The problem is that documentation for an OSS project, 
particularly breaking it down for someone new to the language, is 
a classic tragedy of the commons: work that nobody benefits 
personally from and isn't very interesting to do, so I understand 
why it's the way it is.

I wonder if a possible solution is to automatically generate some 
doc comments and links to glossary/tutorials from the template 
constraints, in addition to the formatting changes others have 
suggested.