Introspect documentation for methods, signals, properties

[Tako Schotanus]

Matthew Johnson wrote:

> On Sat, 18 Feb 2006, Tako Schotanus wrote:
>
>> 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.
>
>
> I've already had someone contribute a dbus 'browser' to the Java
> bindings and I have written an XSL that converts the introspection data
> into a javadoc-like interface description. Both of these could really
> use short descriptions.
>
Heh, funny, I just realised that the guy I responded to is actually the 
author of kdbus ;-)

But yes, I agree, inline-descriptions are the way to go IMO. I do wonder 
if you can force them to be short though. Like I comemnted in another 
message, if the bindings get generated from some C++/Java/whatever API 
it would be logical to use their Doxygen/Javadocs/etc for the 
description in DBus (what else could you use?). But those docs can be 
quite large at times. On the other hand for a browser app it doesn't 
matter so much if you ask for full introspection data and get several 
100KBs of XML because you won't be doing it many times anyway.

Cheers,
-Tako