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

Advertisements
This entry was posted in documentation, eclipse, xml. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s