We need better documentation for functions with ranges and templates

[Jakob Ovrum via Digitalmars-d]

On Tuesday, 15 December 2015 at 03:47:30 UTC, Andrei Alexandrescu 
wrote:
> 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

One possible trick is to use multiple `Params:` sections. 
Optional parameters can be described as such in the parameter 
description to reduce the number of `Params:` sections needed.

Another thing we should do is simplify our overload sets/template 
constraints. For example, `find` has two overloads for needle 
search which can be collapsed into one. They have different 
template constraints - but only because of practical limitations 
in constraining all the needles properly, which should be 
remedied with improvements to std.traits and std.meta.