documented unit tests as examples

[Steven Schveighoffer via Digitalmars-d]

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