Introspection and documenting methods - can I help?
dbus at matthew.ath.cx
Thu Jun 22 05:23:10 PDT 2006
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()
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
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.
More information about the dbus