Re: [boost] dynamically coupling documentation to unit testing

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 
>> 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
>
> _______________________________________________
> Unsubscribe & other changes: 
> http://lists.boost.org/mailman/listinfo.cgi/boost
>