We need better documentation for functions with ranges and templates

[H. S. Teoh via Digitalmars-d]

On Mon, Dec 14, 2015 at 07:04:46PM +0000, bachmeier via Digitalmars-d 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. The example I gave there is
> 
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if
> (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 &&
> !isInfinite!Range2);
> 
> Unfortunately, that's less ugly than for a lot of functions. In some
> circumstances, I can see something like that reminding the author of
> the function about some details, but it can only confuse anyone else.

https://issues.dlang.org/show_bug.cgi?id=13676


> There is nothing I can do about this. Who makes these decisions? Can
> we change it to something useful?

What would constitute "useful" to you?


> Also, I think the documentation for functions involving ranges needs
> more "for dummies" examples. Too many of those functions leave the
> reader not having a clue what to do after calling the function. I know
> how that can be fixed.

Let's see the PR's, then.


T

-- 
The computer is only a tool. Unfortunately, so is the user. -- Armaphine, K5