Proposal: new non-shipping module for examples
bradh at frogmouth.net
Fri Oct 3 01:11:52 BST 2008
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 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
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
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
you can see the linkage back to the main references (including Qt classes),
and if you look at
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
More information about the kde-core-devel