We need better documentation for functions with ranges and templates

[Andrei Alexandrescu via Digitalmars-d]

On 12/14/15 8:10 PM, Chris Wright wrote:
> 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
>    }
> }

We use this pattern in only a couple of places in Phobos, but I think we 
should generally improve the language to use less, not more, of it.

BTW I think all overloads of a given function should be under the same 
DDOC entry with nice descriptions of what cases they apply to. The 
situation right now with many function having separately-documented 
overloads with "Jump to: 2" etc. is undesirable.


Andrei