[RFC] Split tests and examples in KDE4

[Frans Englich]

On Sunday 09 July 2006 21:09, Brad Hards wrote:
> On Sunday 09 July 2006 22:44, Frans Englich wrote:
[...]

> 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.

No problem, I can provide those two examples ;-)

* Full blown "formal" examples. Those are /not/ put in class/function 
descriptions, but are "heavy" and form their own list. Here is a 
demonstration:
http://patternist.sourceforge.net/documentation/API/examples.html

This is achieved with the @example tag, which is documented here:
http://www.stack.nl/~dimitri/doxygen/commands.html#cmdexample

* Inline code examples. These can be achieved in different ways:
- using @code ... @endcode
- using @include to insert a whole file
- using @skip/@until and similar to include an external file while inserting 
comments between lines(e.g, to walk the reader through the code). 

A demonstration:

The code snippets in the docs for ItemType::operator|=():
http://patternist.sourceforge.net/documentation/API/classPatternist_1_1ItemType.html#13e4646cd8494c3e1f366d13337d254d

is actually achieved by inserting this file:
http://patternist.sourceforge.net/documentation/API/Example-ItemType-operator_8cpp-source.html

By using @skip/@until(at the very bottom):
http://websvn.kde.org/trunk/kdenonbeta/kdom/patternist/type/ItemType.h?rev=560154&view=markup

> > 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.

It is great: one can't change the code and then forget to update the examples, 
since the build will break in that case. In Patternist I don't use 
@code/@endcode at all for that reason. Doing the same for kdelibs in the long 
run, is probably a wise idea.

> Might 
> have to poke through Patternist and give that a try.

You're welcome:

* Check out kdenonbeta/kdom/patternist
* run `doxygen` in the dir
* browse kdenonbeta/kdom/patternist/html/index.html

Note that the run can take a while since flow graphs are generated.


Cheers,

		Frans