Introspect documentation for methods, signals, properties

[Tako Schotanus]

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.

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.

But I do think they should be sepearated somehow because you can tell 
people that the documentation should just be short sentences but if I 
remember correctly from the previous discussion, the worry about the 
docs being too long came from the fact that you could auto-generate them 
from the docs (Doxygen/Javadocs/etc) and they tend to be quite long. If 
you seperate them somehow and make sure that everybody who doesn't need 
the docs doesn't aks for them either it doesn't matter IMO if they're 
several 100KBs long or not.

Cheers,
 -Tako