using docbook for API reference documentation

[Stefan Seefeld <seefeld@sympatico.ca>]

Hello,


I have been a happy docbook user for many years. A couple of years ago
I started to write a tool to generate docbook-formatted documentation
from scanning source code, as part of the synopsis project
(http://synopsis.fresco.org).

However, I never really finished the docbook formatter, concentrating
instead on alternative formatters, such as html, texinfo, and pdf.
The reason I didn't move on with docbook was that I couldn't quite
figure out what the best way was to capture all the API artifacts.
While docbook contains lots of markup specifically designed for API
documentation, it wasn't obvious how to map an arbitrary API to
a complete document section (For example: Should the namespace / module
structure directly map to sections ?)

Are there any online resources that discuss useful mappings ? Are
there existing tools (such as doxygen or similar) that generate
docbook ? What docbook conventions do projects such as KDE and GNOME
use for their APIs ?

Any recommendations ?

Many thanks,
		Stefan