On Tuesday, 15 December 2015 at 01:10:01 UTC, Chris Wright wrote:
On Mon, 14 Dec 2015 18:45:28 -0500, Steven Schveighoffer wrote:
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.
This reminds me of the Tango strategy for this kind of thing.
tango.core.Array was arranged like this:
version(TangoDoc) {
/** Documentation comment. */
bool isSameLangth(Range1, Range2)(Range1 r1, Range2 r2) {
return true;
}
} else {
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
if (
isInputRange!Range1 &&
isInputRange!Range2 &&
!isInfinite!Range1 &&
!isInfinite!Range2) {
// actual implementation
}
}
Of course, this was before template constraints -- which in
turn means that the templates they were doing this for were
much more succinct than what you find in std.algorithm, and
they still felt it important to simplify for the sake of
documentation.
It's not ideal because it relies on prose documentation, which
might be far from the implementation, to stay up to date. On
the other hand, it's something that can be done today, without
any changes to ddoc.
An outer template that forwards to specialized templates would
be cleaner.
Hiding conditionals does not seem like to be solution. Here is my
idea:
Show the function:
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
Then show the conditions separately:
if(
isInputRange!Range1 &&
isInputRange!Range2 &&
!isInfinite!Range1 &&
!isInfinite!Range2
)
I am not sure whether ddoc supports/can support this, but being
able to do this, and
even adding separate comment on function and its conditionals
separately could be quite useful. I know just talking doesn't
make anything working, but idea is needed first.
By the way, I wish "and", "or", "xor" were in the language as in
Pascal. Things could be more human friendly maybe.
