Introspect documentation for methods, signals, properties
robert.mcqueen at collabora.co.uk
Fri Feb 17 02:29:18 PST 2006
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
More information about the dbus