I think it's really just a design issue--I agree that you can't
ignore information about ranges and constraints altogether. But
the documentation doesn't reflect any hierarchy of the importance
of information. In the example:
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if
(isInputRange!Range1 && isInputRange!Range2 &&
!isInfinite!Range1 && !isInfinite!Range2);
The most important thing to know is that it accepts two ranges
and outputs a bool. The template constraints are secondary (and
for the most part obvious), but they're in the same visual
hierarchy (line, font size, weight, etc.) as the basic signature.
So it's just extremely noisy.
I think even just putting template constraints in a subordinate
section of the documentation would help a lot. Beginners can just
look at the signature and be good to go 99% of the time; others
can look under the hood easily.
The other noisy aspect is the type repetition of Range1 and
Range2. I don't know what to do about that---maybe a terser
convention for range type params would help. (Typically type
parameters are single letters for this reason in many languages.)
I notice some functions use R1 and R2 instead of Range1 and
Range2.
On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer wrote:
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.
If you're trying to use Phobos without knowing what template
constraints and ranges are, you're going to have a bad time.
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.
It's like trying to use rust with out understanding the
borrowing mechanics. And you can't hide the function signature
from people because it's necessary for people to know what the
constraints for the template arguments are.
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 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.
