Re: [boost] dynamically coupling documentation to unit testing

Subject: Re: [boost] dynamically coupling documentation to unit testing
From: Barend Gehrels (barend_at_[hidden])
Date: 2014-06-25 11:23:57

Hi Roger

Op 25 jun. 2014 om 16:23 heeft Roger Martin <roger_at_[hidden]> het volgende geschreven:

> Hi,
> 
> Been thinking.
> 
> What I've come to like in documentation is a section at the top of a class or functor that includes some real examples code in the 'doxygen' section that shows how to use.
> 
> My question is how difficult would it be to make unit testing pick these up and actually run them? If written with unit equalities this would gain by making me and developers write good header examples at the same time as making unit tests and continuously validate documentation isn't getting out-of-date as well.  And have the output from the tests be compatible with jenkins or other build system's reporting?
> 

Boost.Geometry does this ( or quite similar to what you describe) by having small code samples for (ideally) each algorithm. They are in the doc/src/examples folder. It is not in the form of unit tests because those exhaustingly tests many cases, and the samples are minimal, and have QuickBook markup inside. But it has a Jamfile, is compilable, and automatically included in the docs by QuickBook in combination with Doxygen, in the system we use (we generate quickbook from doxygen xml).

Indeed, what you say, minimal and up to date correct examples are essential.

We might consider move them to the unit test folder to have them in the regression matrix. We have already many things there.... so this has not been done up to now, but this is just a small difference and trivial to change.

Regards, Barend