david at fubar.dk
Fri May 8 07:54:33 PDT 2009
On Fri, 2009-05-08 at 15:46 +0100, Matthew Johnson wrote:
> On Fri May 08 10:26, David Zeuthen wrote:
> > Also, one obvious use of the reference IDL compiler would be to generate
> > nice docs for the D-Bus interfaces that we share via freedesktop.org.
> > Right now, it's XML and that's a bit frightening...
> I've already posted my documentation XSLT (and I think I'm not the only
> one who's written one), but here it is again:
> (sample output: http://mjj29.matthew.ath.cx/dbus-doc/dbus-test.html)
> I was hoping ages ago to make this official, but there was arguments
> that were never resolved about documentation strings.
My view is that doc strings should follow the Java / gtkdoc way of
referencing types/constants, e.g. use # to point to types / constants.
#Foo - points to the type Foo in the current
#org.fd.DK.Disks.AtaSmart - points to a type (a struct in this case in
#org.fd.DK.Disks.AtaSmart.IsFailing - points to a member of a struct
#org.fd.DK.Disks.MediaType - points to an enumeration
#org.fd.DK.Disks.MediaType.MMC - points to a constant in an enumeration
This makes it easy to translate doc-strings into target documentation
formats, e.g. both docbook and gtk-doc for e.g. GObject. It's what I'm
doing here - note that both these pages
are generated from the same introspection XML here
More information about the dbus