X

Musings on JDK development

  • Java
    October 25, 2006

Javadoc tip: Prefer package-info to package.html

While the javadoc for a class should live in that class, where does the javadoc of a package go? A package's javadoc is used to create the text of the package-summary.html page in addition to the tables pointing at the classes and interfaces of the package. Historically, a package.html file was required. However, as of JDK 5, a source file can be used for this purpose, package-info.java. The package-info files were added as part of JSR 175. While their main purpose was to create a living space for annotations applied to a package, they also afford a home for package-level javadoc.

For format of a package-info file is simple:

/\*\*
\* Javadoc comments for package {@code foo.bar}.
\*/
@MyPackageAnnotation
package foo.bar;

I prefer package-info files because they are more regular; source files are used for both class javadoc and package javadoc and the text of the package javadoc can be written in the same manner as normal javadoc.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.