On Friday, 27 March 2015 at 10:10:37 UTC, Dominikus Dittes
Scherkl wrote:
On Thursday, 26 March 2015 at 19:32:53 UTC, Idan Arye wrote:
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.
Unittests are helpful, but I think examples aimed at demonstrating
usage are of more value if possible. Unittests and examples have
subtly different purposes. When writing a Unittest the programmer
will likely take whatever shortcuts they can to get data into the
tested function in the correct format, with the least amount of
code/effort legally possible. Whereas examples (hopefully) will
try
to present inputs in 'real life' scenarios.
If the function inputs are trivial (ie. takes an integer or basic
string) then this isn't an issue. But for functions taking complex
inputs it can be a bit baffling for someone new to the language.
I must admit when I was new to phobos I struggled with the use of
unittests as examples, especially for functions taking
Anyway, unittests are better than nothing - if that is the other
option.
