Introspection and documenting methods - can I help?

[Matthew Johnson]

On Thu, 22 Jun 2006, Daniel P. Berrange wrote:

> My personal preference is to have the documentation "out-of-band" from the
> normal introspection data - separate functional data, from that which is
> merely informative. So adding some form of Introdoc() method would be my
> choice since it avoids breaking backwards compatability, and will avoid
> issue of adding many 10-100's of KB to data returned by existing Introspect()
> method.

I thought adding a parameter (or a second function overloaded with a
parameter) to add documentation annotations was also a reasonable idea.

>> 3. Producing the relevant documentation from the Javadoc/PyDoc/Doxygen source.
>
> There is one other point to be decided before this - namely what format
> should the documentation returned by Introdoc()  be?  HTML, DocBook XML
> fragment per method /property/signal, a complete DocBook XML document
> per interface, plain text, an XML format tailored to DBus, something else?
>
> The critical requirement would be that it must be easy to automatically convert
> from JavaDoc, POD, PyDoc, etc into the format required by DBus, because the
> primary method of documentating classes will always be the language's specific
> format.

Note that Java can't introspect on the Javadoc at runtime so some sort
of off-line conversion will have to happen into a format which can be
read at runtime; probably annotations. In which case I'm in favour of
using the XML format with added human-readable documentation (hence the
flag above). This can be combined with the style sheet I provided on
this list some time ago to render the API similar to Javadoc.

Matt

-- 
Matthew Johnson
http://www.matthew.ath.cx/