documented unit tests as examples

[Meta via Digitalmars-d]

On Friday, 13 May 2016 at 20:39:56 UTC, Steven Schveighoffer 
wrote:
> Just looking at this PR: 
> https://github.com/dlang/phobos/pull/4319
>
> Now the example, instead of running and producing output (i.e. 
> visual feedback) that the program is doing something, just runs 
> and creates no feedback.
>
> I'm wondering if we can have a mechanism for documented unit 
> tests to have a slightly different showing inside the docs vs. 
> the actual unit test.
>
> For example, let's say we have a function writelnAssert. Used 
> like this:
>
> writelnAssert(someText, "Text You Expect To Output");
>
> When running this function, it's basically just an assert that 
> someText == the expected text. However, when DDOC creates the 
> document for this, it says:
>
> writeln(someText); // "Text You Expect To Output"
>
> This way, we are actually testing the output, but at the same 
> time, giving someone playing with the example the tools to see 
> some feedback.
>
> Thoughts?
>
> -Steve

When I was new to D and I first saw the `assert(...)` idiom in an 
example in the documentation, it confused me for a minute or two, 
but if you know what `assert` does you can quickly wrap your head 
around the fact that it's both a test and an example. This would 
benefit users that are completely new to programming in general, 
however.