Source Documentation via XML

by Kenneth Murphy

Introduction

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.

The plan

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.

Progress to date

Current Status: Phase 2

Items currently under development:

To do

Currently, I am needing lots of feedback on the javadoc.dtd. We can't proceed to phase 2 until we feel we are on the right track with the DTD. It doesn't need to be perfect, but it should be close. When I get the next round of feedback, I am planning on adding "import" as an element of class. I am also planning on moving the position of the element "doc" to the start of each place it is appropriate. They will more closely reflect the source code and it just makes since to put the documentation before not after what you are talking about.

Copyright (c) 1999 The Java Apache Project.
$Id: index.html,v 1.3 1999/10/25 14:01:15 stefano Exp $
All rights reserved.