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

[Xavier Bigand via Digitalmars-d]

Le 27/03/2015 15:02, CraigDillabaugh a écrit :
> 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.
>

Just a little point :
I find some much examples not tested on Internet, so to me examples have 
to by played by the compiler in the same time as unittest. Maybe it must 
have a new keyword?

But that true unittest doesn't have exactly the same purpose and some 
risk to be hard to read for a beginner.