Proposal: new non-shipping module for examples

[Brad Hards]

On Thursday 02 October 2008 01:26:44 am Aaron J. Seigo wrote:
> one of the trends i've noticed since starting kde4 is that there is an
> increase in high level documentation[1] and that often includes example
> implementations. these are usually toy apps or artificially simplified
> plugins demonstrating techniques and API usage.
OK, so who are these intended for? In my mind, it is the users of the 
extension APIs who benefit most (which Aaron wrote in a bit I cut: "those who 
benefit the most from examples often aren't building from source but using 
binary packages...").

I think the best approach is to ship it inside the module, with the magic 
KDEMODULE_BUILD_EXAMPLES cmake flags enabling / disabling it, and to link it 
into the API documentation. That helps to keep it in sync, doesn't pollute 
the binaries, but does provide people everything they need to build binaries 
and documentation.

QCA does this. The version of the API docs on http://api.kde.org ignores the 
Doxyfile that ships with QCA (why?), but you can see how it could work at 
http://www.frogmouth.net/qca/apidocs/html/index.html (which is a bit out of 
date as a reference source), or just build the API documentation yourself.

If you look at 
http://www.frogmouth.net/qca/apidocs/html/base64test_8cpp-example.html
you can see the linkage back to the main references (including Qt classes), 
and if you look at
http://www.frogmouth.net/qca/apidocs/html/classQCA_1_1Base64.html
you can see which examples use that particular class.

This is actually pretty easy to do - doxygen does most of the hard work in 
keeping the links working. All you have to do is to add some markup  
for "this file is an example of X" and point doxygen to the examples.

You can put the markup in with any file that doxygen will parse. QCA does it 
this way:
http://websvn.kde.org/trunk/kdesupport/qca/examples/examples.doco?view=markup

Brad