Introspect documentation for methods, signals, properties

[Tako Schotanus]

Kevin Krammer wrote:

>On Friday 17 February 2006 04:30, Rohan McGovern wrote:
>  
>
>>Hi,
>>
>>I think it would be beneficial if DBUS had a standard way of providing
>>short documentation strings on methods, signals and properties in
>>introspect data.  This would avoid the kind of problem DCOP suffers from,
>>where a KDE application can have literally 100+ methods available, but to
>>find out what they actually _do_, a user has to either make a guess based
>>on the method's signature, or look at the source code of the program.
>>
>>It seems that this could easily be done by defining a new well-known
>>annotation, say 'org.freedesktop.DBus.Description' or similar.  Then a
>>DBUS service browser program could easily convey this information to the
>>user.  What do you guys think?
>>    
>>
>
>It might not be necessary to transport the description itself in the 
>introspection data, but rather a kind of reference, i.e. a section in the 
>application's handbook.
>
>  
>
But that would mean that you would need to have those documents 
installed on your system. I think that is not very useful if what you 
want is just some descriptive comments when you use the "DBus Object 
Browser" (ok, that does not exist yet, but I've seen kdbus so things 
like that will become commonplace =). And I don't know if DBus will ever 
be used for communication between systems but then it might happen much 
more often that you won't have those docs installed.

Cheers,
 -Tako