We are currently working on enhancing the documentation provided for the Cocoon XML publishing framework by converting javadoc commented source code into XML for use within Cocoon.

In order to do this we are currently planning to implement the following phases:

1. Develop a JavaDoc XML DTD that acts as a data structure representing the information provided by the rootDoc object of the SUN Javadoc program to a plugged doclet. This DTD is intended to closely mirror the look of a raw java source file.
2. Develop a JavaDoc doclet (JavaDocXML) that takes the information from the JavaDoc rootDoc object and converts it into an XML file using the javadoc.dtd.
3. Wrap the javadoc with XML doclet invocation into a cocoon producer as follows:

• reads the document from the file system
• spawns the javadoc tool using the javadoc XML servlet and using the parameters found in the "javadoc makefile"
• produces the XML output as a single document
• the Cocoon engine process it with the stylesheet indicated (from command line or whatever)
• formats it either as PDF or HTML or whatever depending on the chosen stylesheet. (the HTML formatter will be able to split a single XML document into several ones based on special page-break tags or PIs or using FO directly)
• formatter will also be able to react on the SVG namespace inlining vector graphics or formatted as raster graphics.

4. Some final formats we could produce are:

• javadoc.dtd ---> javadoc_html.dtd ---> HTML (this would create a javadoc that looks like the current HTML javadoc standard).
• javadoc.dtd ---> docBook.dtd (this would facilitate printed books based having heavy content about java API's. For example "The JDBC API Tutorial and Reference: 2nd Edition" could make heavy use of this.
• javadoc.dtd ---> ebook.dtd (this would facilitate the electronic version of documentation)
• javadoc.dtd ---> ??? ---> pdf

5. Using this method we will then enhance the existing Cocoon documentation to provide rich documentation using some subset of the above formats.
6. Finally, we can incorporate XML versions of UML vector diagrams to further enhance the source code documentation.

The first phase has been complete and a complete javadoc DTD was created. We feel confortable with the solidity of that DTD and we plan to move over to the actual XML doclet implementation.

The XML Doclet code (consider it alpha at this point) is included in the Cocoon distribution under /src/org/apache/tools/doclet/xml/XMLDoclet.java.

Being the first two phases complete (the DTD is still in working-draft phase, but it's complete and usable), we need to write the stylesheets that generate HTML out of the javadoc XML files. Any help is always welcome.