John Topley’s Weblog

Javadoc Not Backwards-Compatible

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.

Comments

There aren’t any comments on this post. Comments are closed.

  • avatar Juha Komulainen
    18 May 2004 at 07:09

    Actually Sun's Javadoc guidelines state that you should use code when mentioning keywords and names in the description. That is, in the free-text part of the comment. If you read through the examples, you'll see that they don't use code with the @param arguments. So they have not broken backwards compatibility: you have just relied on bug in Javadoc and gotten away with that until now. But I'm certainly with you on the XML-generation. It would be much easier to gather useful information if I could extract it from XML instead of writing my own doclet.

  • avatar John Topley
    26 May 2004 at 15:37

    Good catch, but the documentation is still contradictory. It all goes to show the hidden implications of making a seemingly simple change to a piece of software that a lot of people are using.

  • avatar philihp busby
    07 June 2004 at 07:49

    XML/XSLT/XHTML/CSS Javadoc'ing would be an awesome improvment.

The Javadoc that ships with the 1.4 JDK nows barfs on documentation written using Sun's recommended style.


Archives

  • Jan
  • Feb
  • Mar
  • Apr
  • May
  • Jun
  • Jul
  • Aug
  • Sep
  • Oct
  • Nov
  • Dec
  • 2017
  • 2016
  • 2015
  • 2014
  • 2013
  • 2012

More Archives


Sign In