What format [Re: Introspection and documenting methods - can I help?]

[Frans Englich]

On Thursday 22 June 2006 08:33, Philip Rodrigues wrote:
[...]
> 3. Producing the relevant documentation from the Javadoc/PyDoc/Doxygen
> source.

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. 
For example:
http://www.docbook.org/tdg5/en/html/funcprototype.html

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).

            <method name="Bazify">
	      <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"/>
            </method>

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:

http://www.w3.org/TR/xmlschema-0/primer.html#CommVers

It feels like that wouldn't be of interest, since it doesn't provide 
interoperability on the documentation's structure.


Cheers,

		Frans