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.

Comments:

Post a Comment:
Comments are closed for this entry.
About

darcy

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today
News

No bookmarks in folder

Blogroll