Re: [PATCH] NM DBUS api documentation build system

[Will Stephenson <wstephenson kde org>]

On Tuesday 05 February 2008 20:55:33 Marcel Holtmann wrote:
> Hi Will,
>
> > > I must agree here. Something that generate the introspection is not
> > > helpful at all. It is hard enough to keep external introspection XML
> > > files in sync with the actual runtime introspection.
> >
> > Surely the glib binding generators create the runtime introspection from
> > the xml files?  That's the way the Qt bindings work.
>
> no they don't. In the dbus-glib case you have the a pre-processing step
> that uses the XML file to generate glue code. You attach this to a
> GObject and then the bindings generate the runtime introspection from
> the runtime information of the object. You could do it without the XML
> file if you really want to.

As far as I can tell looking at dbus-glib, the xml returned by Introspect() is 
generated at runtime from object info statically generated in the glue code 
from the introspection xml files.  Therefore the introspection xml files are 
the original source of the interfaces offered by the objects, therefore these 
are the places where documentation is most effective.

 I'm trying to document the actual implementation of NM 0.7.  I'm aware that 
it's possible to do all this by hand or write a program that doesn't actually 
implement the interface it advertises but those are just hypothetical 
counter-examples.

regards

Will


-- 
Will Stephenson
IRC: Bille