Showing unittest in documentation (Was Re: std.unittests [updated] for review)

[Jonathan M Davis]

On Monday, January 24, 2011 09:55:52 Jens Mueller wrote:
> Jonathan M Davis wrote:
> > In case you didn't know, I have a set of unit test helper functions which
> > have been being reviewed for possible inclusion in phobos. Here's an
> > update.
> > 
> > Most recent code: http://is.gd/F1OHat
> > 
> > Okay. I took the previous suggestions into consideration and adjusted the
> > code a bit more. However, most of the changes are to the documentation
> > (though there are some changes to the code). Some of the code
> > duplication was removed, and the way that some of the assertPred
> > functions' errors are formatted has been altered so that values line up
> > vertically, making them easier to compare. The big change is the docs
> > though. There's now a fake version of assertPred at the top with an
> > overall description for assertPred followed by the individual versions
> > with as little documentation as seemed appropriate while still getting
> > all of the necessary information across. A couple of the functions still
> > have irritatingly long example sections, but anything less wouldn't get
> > the functionality across.
> > 
> > In any case. Here's the updated code. Review away. Andrei set the vote
> > deadline for February 7th, at which point, if it passes majority vote,
> > then it will go into Phobos. The number of functions is small enough now
> > (thanks to having consolidated most of them into the fantastically
> > versatile assertPred) that it looks like it will likely go in
> > std.exception if the vote passes rather than becoming a new module. So,
> > the std.unittests title has now become a bit of a misnomer, but that's
> > what I've been calling it, so it seemed appropriate to continue to label
> > it that way in the thread's title.
> 
> I wonder whether there is a nice way to have unittests included in the
> documentation but also executed. There are lots of examples in the
> module (search for 'Verify Examples').
> I like to avoid this duplication. Has anybody an idea how to achieve
> this? Often the unittests themselves are a pretty good code
> documentation.

I think that it's been discussed a time or two, but nothing has been done about 
it. It wouldn't be entirely straightforward to do. Essentially, either a 
unittest block would have to be generated from the Examples section in the 
documentation, or you'd have to have some way to indicate that a particular 
unittest block got put into the documentation as an Examples section. It's 
certainly true that it would be ideal to have a way to avoid the duplication, 
but we don't have one at the moment, and it hasn't yet been a high enough 
priority to sort out how to do it and implement it.

- Jonathan M Davis