Human unreadable documentation - the ugly seam between simple D and complex D

[H. S. Teoh via Digitalmars-d]

On Thu, Mar 26, 2015 at 07:32:51PM +0000, Idan Arye via Digitalmars-d wrote:
[...]
> uint startsWith(alias pred = "a == b")(Range doesThisStart, Needles...
> withOneOfThese);
>   where:
>     Range is an inferred template argument
>     Needles is a variadic inferred template argument
>     isInputRange!Range
>     Needles.length > 1
>     is(typeof(.startsWith!pred(doesThisStart, withOneOfThese[0])) : bool)
>     is(typeof(.startsWith!pred(doesThisStart, withOneOfThese[1..$])) : uint)
> 
> We've broken the signature into the parts required to use the function
> and the parts required to FULLY understand the previous parts. The
> motivation is that the second group of parts is also important, so it
> needs to be there, but it creates a lot of unneeded noise so it
> shouldn't be a direct part of the signature(at least not in the doc).
> It's similar to the docs of other types used in the signature - it's
> important to have these docs somewhere accessible, but you don't want
> to add them in the middle of the signature because it'll make it
> unreadable.

This is not a new idea:

	https://issues.dlang.org/show_bug.cgi?id=13676

The question is, who's gonna implement it?


T

-- 
If you want to solve a problem, you need to address its root cause, not just its symptoms. Otherwise it's like treating cancer with Tylenol...