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

[Dominikus Dittes Scherkl via Digitalmars-d]

On Thursday, 26 March 2015 at 19:32:53 UTC, Idan Arye wrote:

> The problem, as Andrei Alexandrescu pointed 
> out(http://forum.dlang.org/thread/mdtago$em9$1@digitalmars.com?page=6#post-mduv1i:242169:241:40digitalmars.com), 
> is learning how to use them. Ideally you'd want to be able to 
> look at a function's signature and learn from that how to use 
> it. It's name and return type should tell you what it does and 
> it's argument names and types should tell you what to send to 
> it. The documentation only there for a more through description 
> and to warn you about pitfalls and edge cases.
>
> But when it comes to heavily templated functions - 
> understanding the signature is HARD. It's hard enough for the 
> top programmers that can handle the complex D features - it's 
> much harder for the average programmers that could have easily 
> used these functions if they could just understand the 
> documentation.
I think the documentation should simply contain the unittests - 
they show quite well how to call the template, from minimal cases 
to the complex ones.
Ok, they tend to show a lot of edge-cases, but even the very 
simplest usages of a function should be unit-tested, so at least 
those have to be part of the documentation.