Re: [boost] dynamically coupling documentation to unit testing

Subject: Re: [boost] dynamically coupling documentation to unit testing
From: Adam Wulkiewicz (adam.wulkiewicz_at_[hidden])
Date: 2014-06-25 12:11:14

Barend Gehrels wrote:
> Op 25 jun. 2014 om 16:23 heeft Roger Martin <roger_at_[hidden]> het volgende geschreven:
>> 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.
>
Yes, we could add test directory in geometry/doc directory and treat 
docs as another sublib, like extensions or index.
Put a Jamfile there running test suites doc/src/examples and 
doc/index/src/examples.
Then it should be displayed as a sublibrary of Geometry in the matrix as 
geometry/doc.

Btw, the way how the tests for Chrono are displayed is unique. In the 
BOOST_ROOT/status/Jamfile only chrono/test can be found but the tests 
are displayed as 2 sublibs - chrono and chrono/example. It's because in 
the chrono/test/Jamfile, files from the parent directory are included 
(../example/*.cpp) and bjam handles them somehow, properly in this case.
Is this intentionally supported? I don't know.

Nevertheless I wonder, what if some more complicated path or several 
paths were used this way e.g.:
../doc/src/examples/*.cpp
../doc/index/src/examples/*.cpp

Or the whole test suites:
../doc/src/examples
../doc/index/src/examples

Regards,
Adam