We need better documentation for functions with ranges and templates

[carljv via Digitalmars-d]

On Tuesday, 15 December 2015 at 02:34:01 UTC, Steven 
Schveighoffer wrote:
> Find will handle just about any call you can think of. How can 
> the docs just say this concisely?
>
> -Steve

I think it's an interesting question to what extent template 
constraints are actually suitable at all as human documentation. 
Should treat them as part of the source and hide them? I mean, 
the documentation doesn't include in and out contract conditions 
of functions, which I think are quite close to what template 
constraints are: important information for the compiler, somewhat 
important information for special uses, and mostly  ignorable in 
day to day use. I find many template constraints to be obvious; I 
know I can't ask for the length of an infinite range (the library 
writer is just letting the compiler know). Therefore, giving them 
prominence in the documentation often makes a lot of noise.

There's a spectrum of things from the source code we include in 
documentation. The body of the function, no. Argument and return 
types, yes. Where do template constraints fit into this spectrum? 
If we allow for prose documentation of template constraints, 
should the implementation still be displayed? In how many cases 
is there a clear information gain?