documented unit tests as examples

[Jonathan M Davis via Digitalmars-d]

On Friday, May 13, 2016 16:39:56 Steven Schveighoffer via Digitalmars-d 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?

I confess that I really don't have a problem with assertions being used in
examples like they normally are. That's how unit tests work, and anyone who
uses D for any length of time is going to find that out quickly. And it's
not like you can see the result of writeln anyway unless you copy-pase the
code into an editor to run it yourself, and if you do that, you can replace
the assertion with a call to writeln easily enough. And the assertion can
actually show you the output in the documentation, whereas you won't get
that with writeln. So, if anything, it seems to me that having assertions
that show you the values is better than having to copy-paste the code into
an editor to run it and see the output.

What's a bigger problem is when you want an example that does something like
talk to a website (like std.net.curl does), since it's frequently not
reasonable to have that in unit tests. Fortunately, it's still perfectly
possible to have an untested example if you need it, and it's not usually
needed.

- Jonathan M Davis