Re: [PATCH] NM DBUS api documentation build system

[Will Stephenson <wstephenson kde org>]

On Wednesday 06 February 2008 15:56:32 Dan Williams wrote:
> 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.

The files in introspection/*.xml move to spec/

Will



-- 
Will Stephenson
IRC: Bille