Re: [PATCH] NM DBUS api documentation build system

[Dan Williams <dcbw redhat com>]

On Wed, 2008-02-06 at 09:20 +0100, Will Stephenson wrote:
> 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.

Yeah; the docs, the introspection data, and the generated bindings all
need to come from the same place, and that all needs to be done
automatically.  I don't want to manually update 3 places.  Where do the
current introspection/*.xml files go in your scheme?  The diff removes
them but doesn't apparently add anything back that would describe the
interfaces.

Dan