Introspect documentation for methods, signals, properties

[Thiago Macieira]

Rohan McGovern wrote:
>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?

Makes a lot of sense.

>It might also be nice to change the DTD to allow annotations on
>method/signal arguments.  Combined with the above suggestion, each input
>and output to a method could then be documented in a standard way.

I'm not sure we have to annotate particular arguments. At least, not for 
providing documentation. Maybe for things like default parameters.

A Doxygen-style snippet should be enough:
  This method makes the window wobble and flip.
  \param  msec      the time in milliseconds the window should wobble

The only thing I worry about is memory consumption. Documentation could 
make the XML introspection of a given interface or node quite long. And 
caching all that may prove to be too much. If we decide to go this way, 
I'd like it to be standardised, so I could discard unnecessary data.

(The Qt bindings right now introspect when needed and cache the data for 
the duration of the connection)

-- 
Thiago José Macieira - thiago.macieira AT trolltech.com
Trolltech AS - Sandakerveien 116, NO-0402 Oslo, Norway
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/dbus/attachments/20060217/c6fc8ad0/attachment.pgp