dbus-glib - removing the generated bus method wrappers

[Havoc Pennington]

Matthew Johnson wrote:
> I'll comment on javadoc, I don't know the others.
> 
> Javadoc has @param, @return, @throws tags and a description of the
> function. You can also provide descriptions of classes/interfaces. If
> annotations can be put on methods, interface, arguments; then the method
> and interface documentation annotation can be written straight into the
> javadoc comments and the annotations on <arg direction='in'> turned into
> @param and the annotation on <arg direction='out'> turned into an
> @return.
> 

What I'm wondering about is the other direction. I consider having to 
hand-write the xml files kind of sucky; if doing a binding, I would 
definitely go the route of the old dcop stuff and generate the xml files 
from source code, rather than vice versa.

So given javadoc/doxygen/gtk-doc etc., how do we generate the docs that 
go in a dbus xml file.

The two alternatives I see are:
  - we define some format that goes in the dbus xml file, make binding
    authors write a converter into it for the normal doc system of their
    target language, and have dbus itself implement some converter
    to generate html or whatever from "dbus doc"
  - the dbus xml file has "plain text" or some other unstructured blob

Both of these seem pretty bad, at least for very useful docs. For 
one-liner function blurbs, plain text is probably OK.

If you buy my claim that public APIs should never have generated code 
for a dbus interface in them, then generating docs from generated code 
does not seem all that useful to me.

The use case I'd see for dbus interface docs would be in a dbus 
interface browser or similar tool. Or possibly for people just reading 
the xml files.

Havoc