We need better documentation for functions with ranges and templates

[Adrian Matoga via Digitalmars-d]

On Tuesday, 15 December 2015 at 01:10:01 UTC, Chris Wright wrote:
> 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
>   }
> }

Fantastic example of why this strategy should be just banned. You 
need to duplicate the signature in the source, and you are free 
to make any mistake that won't be caught by the compiler, such as 
the typo in the word 'Length' here. A beginner then copies the 
signature and fills in the argument part, and then spends minutes 
decrypting error messages or even grepping Phobos source to find 
out that the name of the function should be spelled 
'isSameLength', as it's quite easy to overlook, especially when 
you copy-paste from the official documentation, which you expect 
to be correct.