We need better documentation for functions with ranges and templates

[Basile B. via Digitalmars-d]

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:
>
> https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
>
> Something has to be done with the documentation for Phobos 
> functions that involve ranges and templates.

Instead of rewriting all the doc I suggest another approach: 
someone writes a reference article or special phobos page such as

"Understanding D ranges, their constraints and the error 
messages",

that could teach how to interpret and undertstand the error 
messages and the doc. The problem is that new comers really have 
to learn std.range primitives as well as a big part of 
std.traits. The article would cover the most encountered 
functions from this two modules:

- isInputRange
- isForwardRange
- ElementType
- isNarrowString
- ...

Because clearly when you know these functions you understand the 
constraints. That's the key.

~~~~~~~~~~~~~~~~~~~

Another idea would be to put each condition of a constraint on a 
new line (I speak about DDoc formating):

bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
if (isInputRange!Range1
     && isInputRange!Range2
     && !isInfinite!Range1
     && !isInfinite!Range2);


~~~~~~~~~~~~~~~~~~~

In the same vein, but a bit better, put the constraint in a 
separate ddoc section, for example "constraint".