We need better documentation for functions with ranges and templates

[Chris Wright via Digitalmars-d]

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.