Introspect documentation for methods, signals, properties
thiago.macieira at trolltech.com
Fri Feb 17 04:41:27 PST 2006
Robert McQueen wrote:
>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.
I think I misunderstand here the purpose of this documentation.
Is it supposed to be used by running programs at all? Or just shown to the
user when browsing the list of available methods and signals?
I'm suggesting Doxygen because it allows us to:
1) generate HTML, LaTeX, man-page, etc. documentation from installed
interfaces using doxygen
2) put the documentation back into C/C++ header files when creating stubs
for remote objects/interfaces
3) auto-generate this XML documentation by extracting existing Doxygen
documentation in source code
4) not waste time defining yet-another-documentation-format when Doxygen
[#2 and #3 are the two tools missing from the Qt bindings]
But I'd then suggest that, instead of an annotation, we use a
<documentation>....</documentation> tag. That would allow for a better
handling of Doxygen/whatever texts. If modifying the DTD in this manner
is not acceptable, using an XML namespace could be interesting.
>> 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.
Annotations in arguments may be interesting, yes. I am just questioning
whether it makes sense to use it for arguments' documentation.
>> (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
That's a good idea. I should revisit the caching policies in the future.
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
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/dbus/attachments/20060217/9b87e88c/attachment.pgp
More information about the dbus