CK D-Bus docs

[Rob Taylor]

Bringing this to the D-Bus list for wider input...

William Jon McCann wrote:
> 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.

Agreed.

> 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?

Yeah, I think they'd only considered HTML generation. It make sense to
me to have a small set of semantic tags to use insude the docstring block..

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

Thanks!

Rob Taylor