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

Dominikus Dittes Scherkl via Digitalmars-d digitalmars-d at
Fri Mar 27 03:10:36 PDT 2015

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

> The problem, as Andrei Alexandrescu pointed 
> out($em9$, 
> 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.

More information about the Digitalmars-d mailing list