What format [Re: Introspection and documenting methods - can I
englich at kde.org
Thu Jun 22 08:12:26 PDT 2006
On Thursday 22 June 2006 08:33, Philip Rodrigues wrote:
> 3. Producing the relevant documentation from the Javadoc/PyDoc/Doxygen
I don't believe in storing the documentation in a natural language-ish format
such as Doxygen. It is close to impossible to define(let alone massively
labor intensive) and interoperability suffer as a consequence.
I think one should look into an XML solution of somekind. I agree that it is
easily verbose and cumbersome, but I think that drawback is smaller compared
to that one can't convert the documentation into other formats and that the
format is vaguely defined, hurting interoperability.
One could consider embedding XHTML or Docbook inside the introspection format.
One reason is that what belongs to what is naturally resolved, and that the
signatures themselves is documentation too. It makes it simple to find the
documentation for a particular "symbol".
This is possible, with validation and all, if the introspection format is
expressed in XML Schema, as suggested in thread "Namespace and Schema
concerning Introspection Data Format" on this list.
One advantage of Docbook is that it can express functions/classes, and so on.
However, since that structure is already coded in the introspection format, it
could easily be too verbose, making a lighter format more attractive, hence
XHTML. One could simply have a "documentation" element, which could contain
the content of the "p" tag(allowing things like links and semantical markup),
or the content of the "body" tag(a bit heavier, tables and p tags).
<documentation>Turns Foos into a Baz. The result of invoking
this function on Bars is <em>undefined</em>.</documentation>
<arg name="bar" type="(iiu)" direction="in"/>
<arg name="bar" type="v" direction="out"/>
Embedding Docbook/XHTML would make it a piece of cake to transform it into any
other format, in a safe and predicatable way.
Another approach is more generic, such as W3C XML Schema. It simply has
an "annotation" element and doesn't constrain it further. Described here:
It feels like that wouldn't be of interest, since it doesn't provide
interoperability on the documentation's structure.
More information about the dbus