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/[email protected]?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.
