Introspect documentation for methods, signals, properties

[Thiago Macieira]

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

[#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
>and discarded.

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
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/dbus/attachments/20060217/9b87e88c/attachment.pgp