Re: 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