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. 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.
There is nothing I can do about this. Who makes these
decisions? Can we change it to something useful?
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.
I think that most of the problem is simply down to how the
documentation looks. It's too dense.
I think some whitespace and some color-coding will go a long way
to making the function signatures better.
bool isSameLength
(Range1, Range2) // a grey color
(Range1 r1, Range2 r2) // a blue
if (isInputRange!Range1 && isInputRange!Range2 &&
!isInfinite!Range1 && !isInfinite!Range2); // same grey color
as template args, to point out they're working on the template
I think that would make all documentation much easier to glance
over, and yet easy to read if you need to.
On the examples - more examples can only be better!
