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

[CraigDillabaugh via Digitalmars-d]

On Friday, 27 March 2015 at 19:36:23 UTC, Xavier Bigand wrote:
> Le 27/03/2015 15:02, CraigDillabaugh a écrit :
>> On Friday, 27 March 2015 at 10:10:37 UTC, Dominikus Dittes 
>> Scherkl wrote:
clip
>>
>
> 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.

That is a good point.  Ideally when building a library all the 
'examples' in the documentation should be built too to make sure 
they are still valid.  Example code should be marked as such, 
extracted and run through the compiler with each new release.  I 
seem to recall reading in places that some D resources (Ali's 
book perhaps) do this with their source code.

As things stand that would be a mark in favor of unittests.