Introspect documentation for methods, signals, properties

[Daniel P. Berrange]

On Fri, Feb 17, 2006 at 10:58:32AM +0100, Thiago Macieira wrote:
> 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 documentation is only relevant to developers writing / debugging client
bindings - it is informative metdata, rather than functional metata. Mixing
the 2 different kinds of data in the single Introspect() method doesn't seem
like a good idea to me - 99% of the time the docs would be pure overhead.
Thus I'd suggest having a second method on the interface for introspection 
to allow querying of the docs out-of-bound to the normal Introspect() method.

Dan.
-- 
|=-            GPG key: http://www.berrange.com/~dan/gpgkey.txt       -=|
|=-       Perl modules: http://search.cpan.org/~danberr/              -=|
|=-           Projects: http://freshmeat.net/~danielpb/               -=|
|=-   berrange at redhat.com  -  Daniel Berrange  -  dan at berrange.com    -=|
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/dbus/attachments/20060217/0595360c/attachment.pgp