glib bindings (Was Re: [patch] gobject sender and pid)

[Havoc Pennington]

On Mon, 2006-03-13 at 23:28 -0500, David Zeuthen wrote:
> There is no good solution on how to document D-BUS methods yet; where's
> the support in Doxygen or gtk-doc? This is actually a problem we ought
> to solve too :-)
> 

Sure, let's do it ;-)

> And I still maintain that what exceptions a method throws is part of the
> ABI and parts of HAL even rely on this [1]. Thus, it's pretty useful for
> tools that does ABI checking; for example some enterprise Linux vendors
> actually checks this when providing upgrades to customers. So if someone
> wants to update HAL in from RHEL8 to RHEL8U1 and the new HAL now throws
> SomeNewException on the method Foo on interface Bar there's an easy way
> to catch this. This is preferable to just seeing (badly written)
> application XYZ crash or misbehave.

Structured docs should enable the same, though, without misleading
people into thinking the exception stuff is part of the type system or
should be reflected when generating bindings.

> > >  2. Should we install the introspection XML somewhere? As discussed
> > >     in the thread about a year back I don't think there was any
> > >     consensus.. Ideally the hal-devel or PolicyKit-devel RPM packages
> > >     or whatever would include this just like we include header files
> > >     and library stubs in such packages. I don't really think D-BUS
> > >     services are much different.
> > 
> > I don't remember the previous discussions here, surely we have discussed
> > it though?
> 
> I don't remember, sorry, maybe we should discuss it again.

Some starting points:
 - when do you use the dynamic introspection data vs. the files?
 - what if they differ? several cases:
   - same interface is different dynamically vs. in the file
     (can it happen? how?)
   - interface only available dynamically (why?)
   - interface only available statically (why?)
 - if I'm providing an interface, how do I generate the introspection
   file?
 - if I'm consuming an interface, how do I ask for the file?

Some thoughts:

 - ideally the canonical "interface definition" remains the code, i.e. 
   I'd rather just write the GObject or QObject, maybe with some inline
   annotations, maintaining a separate xml file sucks - so the installed
   xml would be a generated file where the generation is 
   binding-specific
 - ideally an interface can be asked for by name, like:
   "dbus-tool --print-interface org.freedesktop.DBus > foo.xml"
   and foo.xml would include only the requested interface, not 
   any other stuff that might have been in the same original file
 - tools could also go directly, 
   "dbus-tool --generate-c-header org.freedesktop.DBus > foo.h"
 - I think it'd be fine, or even good, to distribute the xml file 
   with the app using it; i.e. it's like Makefile.in, not like 
   Makefile - generated by the original developer. Not sure 
   this changes much but maybe it does.
 - on Windows, you can get a COM typelib in C++ like:
   #import "iTunes.exe"
  (or something like that), which in effect includes the header
   file for that typelib. Would be cool to appriximate the same 
   effect...
 - this emphasizes the "if you break an interface you must rename"
   kind of deal (we continue to punt on the interface versioning 
   question, though I thought we had some good consensus on how that 
   could work, nobody coded it)

Havoc