We need better documentation for functions with ranges and templates
Jack Stouffer via Digitalmars-d
digitalmars-d at puremagic.com
Mon Dec 14 11:38:26 PST 2015
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.
More information about the Digitalmars-d
mailing list