John Topley’s Weblog

Although occupationally I currently write code for J2EE 1.3, the other week I needed to install the J2SE 1.4.2 JDK and this led me to discover an interesting difference in the Javadoc documentation program between the two versions.

Following Sun's Javadoc usage guidelines and the excellent The Elements Of Java Style, both of which state that argument names should be offset by <code>…</code>, I've always erroneously enclosed formal method parameters in <code> tags, which causes the parameter name to be displayed in a fixed-width font. I say erroneously because subsequent experimentation has revealed that Javadoc adds the tags itself behind the scenes anyway.

However, that's not what I'm writing about. I discovered that the Javadoc that ships with the 1.4 JDK nows barfs on documentation written using Sun's recommended style. A warning is emitted and the method parameter documentation is not included in the HTML output. To prove this I wrote a simple Java class, that I compiled using both the 1.3 and the 1.4 versions of Javadoc:

public class JavadocTest
{
  /**
   * Program entry point.
   *
   * @param <code>args</code> Command-line arguments to the program.
   */
  public static void main(String[] args)
  {
  }
}

—The 1.3 version works fine as expected, but the 1.4 version gives the warning:

JavadocTest.java:8: warning - @param argument "<code>args</code>" is not a parameter name.

In fairness this behaviour is documented in “What's New in Javadoc 1.4.2” as a resolution to bug ID: 4693440. The bug database entry for this bug says that Javadoc issues a warning when a bad parameter name is passed to the @param tag, and the bug history shows that this fix was introduced because version 1.4.0 onwards requires the first argument to @param to be the parameter name and not the type, as used to be allowed.

Unfortunately this fix doesn't take into account real world Javadoc documentation styles i.e. it's not clever enough to strip the <code> tag from around the parameter name. The net result of which is that potentially I'm now left with a whole heap of legacy code containing Javadoc that no longer compiles cleanly.

Talking of Javadoc, if Sun must break compatibility with previous versions then why don't they improve the standard doclet so that it outputs XML and then uses XSLT to generate valid XHTML? Preferably XHTML that uses DIVs instead of frames and makes more effective use of CSS to produce documentation that is not only functional but attractive too.