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
