[RFC] Split tests and examples in KDE4

[Brad Hards]

On Sunday 09 July 2006 22:44, Frans Englich wrote:
> However, often it isn't as simple as moving the code listing out to a file.
Of course. However we do have some "test" code that could be modified to act 
as examples. It already compiled (and mostly runs).
As an example, see kdelibs/kio/tests/. There are automated tests in 
karchivetest.[h, cpp] for KZip and KTar, but there are manual tests in 
kziptest.cpp and ktartest.cpp. The plan is to move all the testing parts to 
karchivetest, and change ktartest and kziptest to be runnable examples. 

This isn't to say you can't use ktartest and kziptest (or ktarexample and 
kzipexample) to do some developer testing. It is just that the primary 
purpose should be to act as documentation for the classes.

> Most code examples are 5-6 lines taken directly from a function body. If
> that is put in a compilation unit, you'll miss header inclusions and
> typically a wrapping function definition, and usually one doesn't want that
> in the code example.
I think that there are two different things: code snippets (which are inline 
in the class documentation) and compilable examples (which are linked from 
the class documentation). I'll do up an example tonight to show both.

> I solve that by having a central cpp file from which I include other cpp
> files which are the actual examples, or I use Doxygen's @skip/@until
> commands(a bit cumbersome, but it works). Perhaps something like that is
> applicable in this case.
Hmm, never tried generating the code snippets from an external file. Might 
have to poke through Patternist and give that a try. 

Brad