dbus-glib - removing the generated bus method wrappers

[Tako Schotanus]

Havoc Pennington wrote:
> Matthew Johnson wrote:
>> The use case is someone reading the API (which I think should be
>> generated from the XML then rendered in some fashion, or just reading
>> the XML equivelently) to implement a server or a client and not having
>> to founder around because there are no docs (which I've done several
>> times with dbus apps). Having a way to provide a short description
>> easily with your introspection data will help enormously in getting
>> people to actually write these.
>
> Even if we say OK, the docs are in the introspection data xml (which 
> does still raise the issue of how it gets there if not hand-writing 
> said xml), the problem I brought up remains though - what format are 
> the docs in? Are we inventing our own format? Is it "plain text"? How 
> does one correctly display these docs?
>
Well I think that if we allow annotations on arg-elements we could 
probably manage most things with just a plain text annotation. (All 
Java's @param and @return tags could be put in their respective args for 
example)

To keep our options open we could specify that the text should be 
XML-encoded so we can still add some kind of markup in the future if we 
feel the need for it.

Or we could just define an annotation (eg 
org.freedesktop.DBus.Description) to be plain text and nothing else. And 
if in the future we find that we need a richer format we could add 
another annotation (eg org.freedesktop.DBus.RichDescription). Of course 
to be backward compatible it might mean that you have to add both 
annotations (or that Description is automatically filled with a stripped 
version of RichDescription).

Dunno, just some ideas.

-Tako