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

[Jens Mueller]

Jonathan M Davis wrote:
> 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.

I see. I understand that it does not have high priority. Just wondered
whether ...

Jens