Extended introspection

[Havoc Pennington]

Hi,

On Tue, Jun 17, 2008 at 7:17 PM, Michael 'Mickey' Lauer
<mickey at vanille-media.de> wrote:
> So, what's the recommended way to document the semantics then? It hardly makes
> sense seperatly bookkeeping your documents apart from the interface. The dbus
> introspection format is seriously limiting for documentation and we'll see
> all kind of different proprietary extensions coming up.
>
> Do we care?
>

The original design intent was that nobody would write the
introspection format by hand. It's intended to be a mostly
machine-readable intermediate format.

The idea is that you can write docs and define an interface in the way
you're used to in some native system, such as QObject or
java.lang.Object or even a corba-like IDL. This is then exported in
automated fashion to the message bus.

There are various gaps between ideal and reality, for example the dbus
glib bindings have never been completed. The intent of the dbus glib
bindings design was that in the long term, the xml would be
automatically generated from gobject-introspection, and in the short
term a source code scanner would create the xml. But in practice the
source code scanner was not written, so people hand-write the xml.

Docs support in the xml could still be useful for tools like d-feet,
but the docs support in the xml isn't supposed to be how you *write*
the docs.

Struct names and struct field names would be fine to have in the
introspection I think, I'm sure there are some old threads about it.
But they would be optional hints, really. This sort of thing is a help
to static languages such as C++ and kind of a pain for people using
dbus from python or other dynamic languages. My opinion is that best
practice is to avoid complex types (structs in particular) in most
cases, because they are a pain in the ass from any dynamic binding.
Dynamic bindings include static languages, but it's also possible (and
IMO desirable) to do the binding for a static language in a dynamic
way, i.e. without generating static stubs.

Dictionaries are much nicer for dynamic bindings, since they include
field names on the wire instead of relying on the ordering of the
fields. Structs are most useful when you want to efficiently send a
big array of them, like an array of rectangles or something like that.

Anyway, it would be worthwhile probably for someone to write up a mail
linking to some old archived discussions on docs, field names, and
other introspection extensions; and to survey what current language
bindings are doing; and then with the data collected and summarized,
propose the right common denominator to put in the spec to be shared
among bindings. Without doing that work I doubt anyone could say a
priori what the right introspection format extensions would be.

Havoc