Introspect documentation for methods, signals, properties

[Daniel P. Berrange]

On Sat, Feb 18, 2006 at 06:07:38PM +0100, Tako Schotanus wrote:
> Daniel P. Berrange wrote:
> >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.
>
> True, altough when this discussion popped up before we had thought about 
> making it a parameter to the Introspect method where you could tell it 
> to provide documentation or not. Having one document with the 
> documentation next to their relevant items is a bit easier to handle 
> than having two documents which you have to match up somehow.

Yeha, that's a possiblity, but I think we'd want to check that adding a
parameter doesn't cause any compatability problems for existing bindings.
I don't think it should, but its wise to verify.

> I'm also "afraid" that people will implement Introspect() but will 
> somehow "forget" Introdoct() or that it will be more difficult to keep 
> both up-to-date. Of course that problem doesn't go away if there's only 
> one document but it tends to remind people that they have to adjust 
> their docs as well if the docs are close to the lines they're changing.

Well app developers don't typically implement the Introspect() method
themselves. The language specific bindings implement it on their behalf,
with underlying data obtained via reflection, or inline annotations. I'd
anticipate that the documentation would be dealt with the same, for example,
extracting the JavaDoc, or Perl POD, etc. So there wouldn' be any issue
with developers forgetting Introdoct(), because they just be documenting
their methods in the language-native way & Introdoct() done for them.

Regards,
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/20060218/b70fbdb5/attachment.pgp