IDL language

[David Zeuthen]

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:
> 
> http://mjj29.matthew.ath.cx/dbus-doc/ 
> (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.
For example

 #Foo                       - points to the type Foo in the current
                              namespace

 #org.fd.DK.Disks.AtaSmart - points to a type (a struct in this case in
                             another namespace)

 #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

http://people.freedesktop.org/~david/eggdbus-HEAD/eggdbus-eggdbusbus.html
http://people.freedesktop.org/~david/eggdbus-HEAD/eggdbus-interface-org.freedesktop.DBus.html

are generated from the same introspection XML here

http://cgit.freedesktop.org/~david/eggdbus/tree/src/eggdbus/org.freedesktop.DBus.xml

    David