D-Bus API description to include dox?

[Will Stephenson]

On Monday 22 March 2010 13:36:58 Friedrich W. H. Kossebau wrote:
> doing the KRemoteControl review I wonder why there is no API dox considered
> for the D-Bus introspection, one has to guess the semantics of all the
> methods and parameters.
> 
> Should we extend the dtd to include that? Anyone with insider knowledge how
> to get this best done? Can we at KDE at least start to do so, by using
> comment sections (<!-- -->) in the api.xml file?

One way to do it is used by telepathy and (after yours truly ported the docu 
generation from telepathy) NetworkManager.  It uses namespaced xml elements in 
the dbus introspection and some XSLT magic to transform that into HTML 
documentation.  Examples:

http://cgit.freedesktop.org/NetworkManager/NetworkManager/tree/docs/Makefile.am
http://cgit.freedesktop.org/NetworkManager/NetworkManager/tree/introspection/nm-
manager.xml

Will