Java 5 has improved the javadoc support for packages so that they can now be documented in a new package-info.java file as regular javadoc comments (on the package declaration), rather than having to create an obscure package.html file, without editor support for links and without really knowing what to put in the html file - formatting? headers?. Eclipse 3.3 recognises these files and javadoc comments, including code completion, but does not produce valid javadoc comments — the code completion will:

  • Insert only the class name, not the fully qualified name of the link
  • Add an import statement to the top of the file, which is not allowed in package-info.java

The comments looks like the following after removing the invalid imports, but the generated javadoc doesn’t include any of the links, since they have to contain fully qualified package names.

/**
 * Tests java functionality.
 * Many tests are performed in {@link MyTestClass}
 */
package com.tildemh.test;

Google isn’t my friend today, so does anyone reading this know how to fix eclipse, e.g. to always use the fully qualified name in javadoc comments?

update

The javadoc documentation states that package-info.java files should always use fully qualified names. I’ve opened an eclipse bug about this.