We need better documentation for functions with ranges and templates

[carljv via Digitalmars-d]

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.