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