We need better documentation for functions with ranges and templates

[tcak via Digitalmars-d]

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.