dbus-glib - removing the generated bus method wrappers

[Havoc Pennington]

Thiago Macieira wrote:
> The interface XML's author should accept patches from people trying to 
> bind to it if those modifications are necessary. Think of it as analogous 
> to a C++ developer asking a C maintainer to add
> 
> #ifdef __cplusplus
> extern "C"
> #endif
> 
> guards to his C headers, so that they can be used from C++ as well.

In this case it might be quite a lot of stuff like that, and also some 
of it subjective or app-specific; e.g. there might be a desired 
annotation for namespace to generate methods in, or an annotation for 
the existing, legacy function name to use to implement a server method, 
or whatever...

> Not so with the Qt bindings. If you use any complex type (structs or any 
> array that is not "as" or "ay", including the dictionaries), you need to 
> tell the binding tool which class name that is. Otherwise, it'll skip the 
> generation completely.
> 
> Merging XML data shouldn't be difficult, though. I hadn't thought about 
> that. But between maintaining two files in sync with each other and 
> maintaining a single one, I'd rather do the latter.

Originally I envisioned dbus-binding-tool as helping with making all 
this really nice. It has an idea of multiple backends; if it became more 
general and didn't only support glib-related stuff, potentially this 
tool should be in the main dbus tree.

A couple of examples.

In the specific case mentioned here, I'd imagine something like:
  dbus-binding-tool --extract-interfaces MyAppDBusStuff.xml \
                    --output-dir $(builddir)/dbus-interfaces

In this case, you would maintain the app-specific annotations and all 
your interfaces in one nice convenient file; then the binding tool sucks 
out the interfaces "cleaned" and in properly-named files for 
installation purposes.

If there were docs in MyAppDBusStuff.xml those could be sucked out into 
some form also.

A second example, the way the glib bindings originally were intended to 
work was like DCOP; you would have a plain .c file, with "magic 
comments" when needed, which would be scanned and the object interfaces 
extracted to XML introspection data. This introspection data could then 
be installed, or used by other bindings, or whatever.

I believe the way they work now is that you have to type the XML data 
manually, but that was NOT the intent, just that nobody ever wrote the C 
scanner.

This dbus-binding-tool approach would also have the benefit of letting 
us validate correctness, check for following various rules, ensuring 
consistent file naming, etc.

> However, the installed files should contain documentation. It's even more 
> important than introspection over running programs.

An idea I just had, what about a consistent mapping from a given 
interface/member to some tree of HTML on the filesystem? The HTML would 
be generated in whatever way people see fit, but the URLs would be 
specified. It's one thought anyway.

What I mean is that e.g. 
file:///datadir/dbus/interface-docs/org.freedesktop.Hal.Whatever.html#Frobate

is supposed to exist if we have the method Frobate on
interface org.freedesktop.Hal.Whatever

The app developer could then generate that from source code comments, or 
we could support an annotation in the MyAppDBusStuff.xml that 
dbus-binding-tool would suck out when it also sucks out the interfaces, 
or people could even write the HTML by hand. All the ways of generating 
the HTML would interoperate though since a documentation-displaying tool 
could just know the format of the URLs.

This might lead to inconsistent presentation (different stylesheets and 
markup conventions in the various html files), but it might also be 
helpful for actually getting docs written, and keep the dbus maintainers 
out of the business of maintaining some kind of doc system.

Havoc