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

[CraigDillabaugh via Digitalmars-d]

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.