Subject: Re: [boost] dynamically coupling documentation to unit testing
From: Roger Martin (roger_at_[hidden])
Date: 2014-06-27 11:51:48
Thank all of you for pointing to examples. I'll look and learn
On 06/25/2014 12:11 PM, Adam Wulkiewicz wrote:
> 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
>> 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
> 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.:
> Or the whole test suites:
> Unsubscribe & other changes:
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk