We need better documentation for functions with ranges and templates

[Steven Schveighoffer via Digitalmars-d]

On 12/14/15 2:04 PM, 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);

This is by far, one of the least problematic examples.

A while back, I wanted to use std.algorithm.find to search for 
something. I wasn't sure what order to call the parameters with, so I 
looked at the documentation. After about 10-15 minutes of trying to 
deduce whatever template overload was going to match, if any at all, I 
just decided to write the call and see if it worked (it did).

The documentation for IFTI functions like this needs to be simplified 
greatly. Essentially, I need to know what types of things I can use, and 
what order I need to pass them. But I don't need all the details of 
which overload will be called depending on some obscure template constraint.

I don't know if there's an automated way to do this. IFTI functions are 
so powerfully useful, that it's almost impossible to have this done 
automatically.

In the example of find, a possible way to do this is to wrap the whole 
set of overloads into one simplified call:

Range1 find(Range1 haystack, N needle)

And then explain what Range1 and N can be. Then allow one to expand the 
docs to see all the true signatures if I want to.

In std.conv, there is a global template to that forwards to all the 
different toImpl, with the majority of docs on the to template. That is 
kind of the model I was thinking of, but allow ddoc to hide all the 
implementation details and show on demand.

-Steve