Introspect documentation for methods, signals, properties

[Rohan McGovern]

On Fri, 17 Feb 2006 19:58, Thiago Macieira wrote:
> Rohan McGovern wrote:
> >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
> 

That would be fine also, but the exact format should really be a part of 
the spec.  I mentioned annotating parameters because I imagined that 
different people would be totally inconsistent.  Each of the following 
probably sounds like a good idea to someone:
"...and flip.\nmsec: the time in..."
"...and flip. PARAMETERS: msec - the time in..."
"...and flip\n at param msec the time in"

That would make it practically impossible for a program to always be able 
to pick out which parts of the documentation refer to parameters.  Putting 
parameter annotations into the DTD itself would make it a lot harder to be 
inconsistent.

Rohan
-------------- 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/e70609a7/attachment.pgp