documented unit tests as examples

[Ryan Frame via Digitalmars-d]

On Saturday, 14 May 2016 at 17:48:48 UTC, Andrej Mitrovic wrote:
>
> So anyway, I think perhaps the simplest solution is to make 
> ddoc inject the writeln calls (or possibly replace assertions 
> altogether in the output).

The problem with replacing the assert is the loss of information.

assert(sum(2, 2) == 4);

tells me what sum(2, 2) should return merely by reading the 
example, but

writeln(sum(2, 2));

requires me to run it (or re-read the documentation for sum(), 
but the example is supposed to save me from that). Merely 
injecting the writeln() provides full return information when 
reading and executing the example (though more context should be 
provided than just the return value).