Generating documentation for DBus APIs

[Dave Neary-5]

Hi,

I'm looking for documentation of the various DBus interfaces that get
published by an application, and for the moment I can't find any. It's
leading me to think that maybe there is no way to automatically generate
documentation of interfaces the way Doxygen of gtk-doc do for APIs.

Is that the case? Or is there a tool that I can run on the source code
to generate docs for DBus interfaces?

If there is no such tool, is there a recommended way to browse DBus
interfaces on a running system? I found d-feet, which looks cool - the
only thing I'm missing is the semantics of what the various methods,
paths and interfaces do - I just get interface names, paths and method
names with type information.

The kind of thing I'd love to see, ideally, would be something like the
GIMP's plug-in browser:
http://www.linuxtopia.org/online_books/graphics_tools/gimp_user_manual/en/gimp-xtns-plug-in-browser.html

Cheers,
Dave.

--
maemo.org docsmaster
Email: dneary@...
Jabber: bolsh@...



_______________________________________________
dbus mailing list
dbus@...
http://lists.freedesktop.org/mailman/listinfo/dbus

[Michael 'Mickey' Lauer-3]

> I'm looking for documentation of the various DBus interfaces that get
> published by an application, and for the moment I can't find any. It's
> leading me to think that maybe there is no way to automatically generate
> documentation of interfaces the way Doxygen of gtk-doc do for APIs.
>
> Is that the case? Or is there a tool that I can run on the source code
> to generate docs for DBus interfaces?

Various groups have created tools to parse XML introspection files, such
as you can see at http://telepathy.freedesktop.org/spec-0.18/ and
http://docs.freesmartphone.org -- unfortunately this file format lacks a
lot, so we can see several incompatible vendor-specific enhancements.

> If there is no such tool, is there a recommended way to browse DBus
> interfaces on a running system? I found d-feet, which looks cool - the
> only thing I'm missing is the semantics of what the various methods,
> paths and interfaces do - I just get interface names, paths and method
> names with type information.

d-feet, qdbus, mdbus, there's a bunch them.

:M:


_______________________________________________
dbus mailing list
dbus@...
http://lists.freedesktop.org/mailman/listinfo/dbus

[Bastien Nocera]

On Thu, 2009-11-12 at 11:43 +0100, Dave Neary wrote:
> Hi,
>
> I'm looking for documentation of the various DBus interfaces that get
> published by an application, and for the moment I can't find any. It's
> leading me to think that maybe there is no way to automatically generate
> documentation of interfaces the way Doxygen of gtk-doc do for APIs.

You can use gtk-doc, which would generate something like that from the
XML interface definitions:
http://people.fedoraproject.org/~hadess/fprintd/docs/

xdg-hostname, and fprintd have examples of how to use DavidZ'
stylesheets to generate the documentation.

Cheers

_______________________________________________
dbus mailing list
dbus@...
http://lists.freedesktop.org/mailman/listinfo/dbus

[Will Thompson-5]

On 12/11/09 10:43, Dave Neary wrote:
> Hi,
>
> I'm looking for documentation of the various DBus interfaces that get
> published by an application, and for the moment I can't find any. It's
> leading me to think that maybe there is no way to automatically generate
> documentation of interfaces the way Doxygen of gtk-doc do for APIs.

The Telepathy interface definitions[1] are written using D-Bus
introspection XML, extended to include documentation. Then we have a
tool to transform that into HTML documentation[2], and build a Devhelp
index.

You could run that tool on the introspection XML for other projects, but
it won't be annotated with the per-argument documentation that the
Telepathy spec XML is, so it's not exactly what you're looking for.

(I wasn't aware until 30 seconds ago that gtk-doc supports building docs
from a presumably-different set of extensions to the introspection XML.
It'd be good to standardize on something.)

[1] http://git.collabora.co.uk/?p=telepathy-spec.git;a=summary
[2] For example,
http://telepathy.freedesktop.org/spec/org.freedesktop.Telepathy.Connection.Interface.Requests.html


--
Will
_______________________________________________
dbus mailing list
dbus@...
http://lists.freedesktop.org/mailman/listinfo/dbus