Automated SDK JavaDoc Documentation

One of the pain points with working with eclipse, is generating the SDK documentation (bug 231472). Typically this is done by using the standard javadoc command, and outputting HTML files. The toc.xml files, then need to be updated manually to link to the appropriate HTML files. However, sometimes this doesn't integrate well with how the other documentation is integrated into eclipse. Mainly because the linking is done to the Frames content of the javadoc file, and it just looks messy.

The reason some plugins do this, is that hundreds if not thousands of individual javadoc html files can be generated. What is needed is some way to get this information into a format that can be used to generate automatically the toc.xml file, and any supporting html files in one or two steps.. After searching around for a while, I think I have a possible solution. There is a little known doclet hiding on sourceforge called JELDoclet. It generates an XML file from the javadoc.

<jelclass superclass="NLS" visibility="public" superclassfulltype="NLS" fulltype="org.eclipse.wst.xsl.core.internal.Messages" type="Messages" package="org.eclipse.wst.xsl.core.internal">
<comment>
 <attribute name="@author">
    <description>Jesper Steen</description>
 </attribute>
</comment>
<fields>
  <field visibility="public" fulltype="java.lang.String" type="String"  name="XSLCorePlugin_parserConfiguration" static="true">
    <comment>
      <description>TODO: Add JavaDoc</description>
    </comment>
  </field>
  <field visibility="public" fulltype="java.lang.String" type="String" name="XSLCorePlugin_badInitializationData" static="true">
    <comment>
      <description>TODO: Add JavaDoc</description>
    </comment>
  </field>
  <field visibility="public" fulltype="java.lang.String" type="String" name="XSLCorePlugin_coreError" static="true">
    <comment>
      <description>TODO: Add JavaDoc</description>
    </comment>
  </field>
</fields>
<methods>
   <constructor visibility="public" name="Messages" />
     <method visibility="public" fulltype="void" type="void" name="reloadMessages" static="true">
   <comment>
      <description>TODO: Add JavaDoc</description>
   </comment>
</method>
</methods>
</jelclass>

The easiest way to generate this file is with an ANT script using the javadoc task:

<javadoc destdir="doc" package="true" docletpath="${workspace}/lib/jeldoclet.jar">
<fileset dir="${workspaceloc}/org.eclipse.wst.xsl.core/src">
  <include name="**/*.java"/>
</fileset>
<doclet name="com.jeldoclet.JELDoclet" />
</javadoc>

JELDoclet has options to generate a single XML file that contains everything (ideal if you are creating docbook or dita files). Or it has the ability to generate single xml files for each class (ideal for generating html files from xml). Either way, by having an XML representation of the JavaDoc one can manipulate and start to automate the process of generating the appropriate toc.xml file for eclipse documentation.

Ideally, one could convert the XML file to Docbook and then run it through the eclipse.xsl file to generate the appropriate plugin with corresponding indexed HTML and toc.xml created. If this was included in a feature build for an SDK plugin, then there would be no reason for the SDK documentation to be out of date with the HTML documentation. It provides a fairly simple method for keeping the two in synch. It doesn't levitate the need for the committers to make sure that the javadoc documentation itself is accurate, or even if everything is documented. To do the latter, one would need to run the doclet DocCheck across the code.

So feel free to voice your opinion on bug 231472, if you agree with this approach or have another way to make sure that the sdk javadoc documentation is easy to create.