Introspect documentation for methods, signals, properties

[Robert McQueen]

Thiago Macieira wrote:
> 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

Surely this is harder to parse and worse than just putting an annotation
on each argument? There's no reason to define a crappy new format when
we're already in a strictly structured XML tree that already deals with
the exact same entities we're interested in.

> 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.

Yes, it should be allowable to annotate every parameter, method or
interface, and have them all be org.freedesktop.DBus.Documentation. Then
if you're not interested, discard all of these annotations.

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

As do the Python bindings, but they only cache the information they
actually need for ongoing usage - unknown annotations are simply ignored
and discarded.

Regards,
Rob