documented unit tests as examples

[Seb via Digitalmars-d]

On Friday, 13 May 2016 at 21:27:25 UTC, Steven Schveighoffer 
wrote:
> A potential way to fix this may be marking a unit test as being 
> a complete example program that assumes the user has installed 
> proper access to the library. Then it won't compile unless you 
> add the correct imports, and it's treated as if it were in a 
> separate module (no private symbol access). This is probably 
> the closest we can get to simulating a user copying an example 
> unit test into his own file and trying to run it.
>
> -Steve

Maybe I should have stated that I discovered that the in-text 
example is broken, because I was working on this new feature: 
https://github.com/dlang/dlang.org/pull/1297 (allow all unittests 
in Phobos to be run online via DPaste).
So yep for this feature to work smoothly we either need to 
auto-detect what other imports (except for the current module) 
are needed, or force Phobos devs to explicitly import other 
modules in ddoced unittests. I would also prefer the latter.
Anyways this example didn't run, because the import std.conv 
wasn't imported and the idea to put tests whenever possible from 
plaintext to D code is too ensure that are actually working ;-)

@Steve: I do understand you partially - I don't like assert that 
much either, because when it breaks you don't know why. That's 
why I would prefer if we would have something like

assertEqual("a", "b")

in Phobos and most of the tests.
The rationale is that it breaks with a proper error message 
instead of just saying - hey you have some error there. We still 
could automatically replace this to writeln(a); // b, but I think 
having a proper equal should already be a lot better and people 
hopefully can then just put in a different value for 'b' to see 
the test fail.

Here are some numbers, from in total 28761 assert's in Phobos

- 15266 use "==" (53%)
- 1451 use equal (5%)
- 165 use approxEqual (0.6%)

- 452 assert(0
- 5165 static assert