>To JavaDoc or Not JavaDoc..Part Deux

>Automating Java API Reference Plugins.

One of the things that Eclipse PDE is missing is a nice way to generate SDK javadoc help plugins. The nice thing about living in the Internet age, is that somebody else has probably already invented the necessary code. They probably even have it available for download as well. I blogged a while ago about my disappointment with the lack of up to date javadocs in some eclipse projects. Now there is little excuse.

I like to automate as much as possible, this includes generating any sort of documentation and only having one source to maintain and update. So, if I can find a way to automate this currently manual process, so much the better. It just so happens that Mariana Alupului from IBM, has written an article called, “Java API reference documentation“. The third part of the article, which the link sends you to, covers how to automate the creation of the Java API reference documentation for your various plugins.

Docbook Doclet:

Another alternative for those that like sticking with XML formats, is to use Michael Fuchs, Docbook Doclet program to generate Javadoc as Docbook files. From here, you can then run the Docbook Stylesheets to generate a wide variety of output formats, including eclipse help format. This is a little out of date, and I do have an updated version of this stylesheet in development which correctly generates an eclipse 3.1+ formatted plugin.

Doclets…Doclets..Everywhere:

A large variety of doclets are available. If you can think of some sort of output format, more than likely Doclet.com has it.

Build SDK Documentation Nightly:

There really should not be a reason that the javadoc for plugins is not automatically built and packaged along with all of the other artifacts. Where I work, we have incorporated the building of all of our documentation for the standards we produce, into the same nightly builds. The documentation is generated from the source files, so when we update the source files, the documentation is generated and updated as well. The links above are a couple of ways that this can be accomplished. I’m sure that the PDE team will eventually create such a beast. If you are interested in this functionality, voice your opinion on bug 231472. In the meantime, start automating your sdk documentation plugins.

Advertisements
This entry was posted in docbook, documentation, eclipse, java. 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