CK D-Bus docs

[William Jon McCann]

Hi Rob,

On 3/9/07, Rob Taylor <rob.taylor at codethink.co.uk> wrote:
> William Jon McCann wrote:
> > I've started adding documentation to ConsoleKit and I came up with
> > something that might be of use to others.
> >
> > Hopefully I haven't just reinvented a wheel but I wrote a little tool
> > to turn D-Bus glib .xml files into DocBook refentries.
> >
> > http://gitweb.freedesktop.org/?p=ConsoleKit.git;a=blob;hb=HEAD;f=doc/docize-dbus-xml.sh
> >
> > http://gitweb.freedesktop.org/?p=ConsoleKit.git;a=blob_plain;f=doc/docbook-dbus.xsl
> >
>
> You might want to check out the doc generation stuff that the Telepathy
> guys use, darcs get
> http://projects.collabora.co.uk/darcs/telepathy/telepathy-spec and look
> in ./tools.
>
> I really think it'd be nice to have some sort of standard dbus interface
> documentation method, so I'd be interested in your take on things :)

Actually I think the source .xml files are the interesting part:
http://projects.collabora.co.uk/darcs/telepathy/telepathy-spec/spec/Connection.xml
(probably have to view page source to see the tags)

Which seem to be documented here:
http://telepathy.freedesktop.org/wiki/DbusSpec

So it is similar to what I was suggesting in that it extends the
introspection format to include documentation.  In this case the
documentation is provided by adding a <tp:docstring> element that may
contain XHTML.  The other stuff about documenting errors and enums
seems pretty sane too.

I'm not sure about just using a XHTML blob for the docstring since
that may make it harder for the blob to be used either structurally or
semantically.  Of course, if I'm just rendering this .xml file to the
web then it is fine.  But what if I am translating this .xml file into
a docbook?  What can I do with the XHTML?  Well, there is no semantic
information that I can use to translate it directly into native
docbook markup.  Also, it requires that a tool used to translate
dbus-xml to any other format (docbook, plain text, etc) must support
the entire XHTML spec (all allowed elements).  Yikes.

I think it is much simpler to just define a small set of documentation
tags that we allow to be used inside a <docstring> block.  And with
those tags we should probably stay closer to gtk-doc and docbook than
xhtml (which should probably be reserved for use as one of the views
of this data rather than the source model).  I'll try to play with
this and come up with a concrete proposal.

What do you think?

Jon

PS: Noticed this while testing this stuff (my patch was incomplete the
last time):
https://bugs.freedesktop.org/show_bug.cgi?id=8607