We need better documentation for functions with ranges and templates

[Andrei Alexandrescu via Digitalmars-d]

On 12/14/15 10:51 PM, Jakob Ovrum wrote:
> 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.

Yah, these are sensible ideas. Please add them to 
https://issues.dlang.org/show_bug.cgi?id=13676. Thanks! -- Andrei