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