How to add package level comments in Javadoc?

Question

I am using CheckStyle, FindBugs, and PMD to validate my Java code. I have fixed almost all the bugs caught by these tools.

I am not able to understand how to write "package comment" which is a bug caught by checkstyle. I have gone through the documentation of CheckStyle, but I don't understand it.

Could someone help me in writing a package level comment in Java?

score 76 · Answer 1 · edited Jun 10 '14 at 17:19

76

Package-level javadoc comments are placed in a file named package-info.java inside the package directory. It contains the comment and a package declaration:

/**
 * Provides the classes necessary to create an applet and the classes an applet uses 
 * to communicate with its applet context. 
 * <p>
 * The applet framework involves two entities: 
 * the applet and the applet context. An applet is an embeddable window (see the 
 * {@link java.awt.Panel} class) with a few extra methods that the applet context 
 * can use to initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see java.awt
 */
package java.lang.applet;

This is documented here: Package Comment Files

edited Jun 10 '14 at 17:19

Kevin Panko

8,356
19
50
61

answered Sep 06 '10 at 11:07

Michael Borgwardt

342,105
78
482
720

Interesting. The page about writing comments for Javadoc (see my answer) doesn't even mention this. – Thomas Owens Sep 06 '10 at 13:33
@Thomas: keeping overlapping documentation consistently up-to-date is a bitch. – Michael Borgwardt Sep 06 '10 at 14:07
2

Indeed it is. I would have suspected that Sun (and now Oracle) would have done a better job with maintaining documentation. Especially since I've been doing Java development for over 5 years now and have never seen or heard of this method of producing package-level documentation before. – Thomas Owens Sep 06 '10 at 14:24
@MichaelBorgwardt, Is there a way to add the "Overview" section for javadocs? (as can be seen on http://docs.oracle.com/javase/6/docs/api/overview-summary.html) – Pacerier Aug 15 '14 at 17:51

score 29 · Answer 2 · edited Mar 12 '13 at 15:46

29

Create a file package-info.java in your package to document
Add the package descriptor
Add a comment (/** ...*/) before the package declaration

The following link provides more information: http://docs.oracle.com/javase/specs/jls/se5.0/html/packages.html

It is recommended that package-info.java, if it is present, take the place of package.html for javadoc and other similar documentation generation systems

Package wide annotations will also be declared at package-info.java

Greetz, GHad

edited Mar 12 '13 at 15:46

Hasturkun

35,395
6
71
104

answered Sep 06 '10 at 11:05

GHad

9,611
6
34
40

1

I have never heard of this method before. Can you provide a link to a document that describes it? – Thomas Owens Sep 06 '10 at 11:07
1

@Thomas Owens http://java.sun.com/docs/books/jls/third_edition/html/packages.html – emory Sep 06 '10 at 11:10
Form the link: It is recommended that package-info.java, if it is present, take the place of package.html for javadoc and other similar documentation generation systems. – GHad Sep 06 '10 at 11:20
Those links really need updating they are way out of date. – Andrew S Apr 13 '23 at 01:33

score 5 · Answer 3 · answered Sep 06 '10 at 11:04

5

You have to make a package.html page located within the package. You can read about the contents and structure of this file on the How to Write Doc Comments for the Javadoc Tool page.

answered Sep 06 '10 at 11:04

Thomas Owens

114,398
98
311
431

1

I suppose this is because of not mentioning package-info.java at all (which is the preferred variant nowadays). – Paŭlo Ebermann Dec 02 '11 at 19:08

score 3 · Answer 4 · edited May 23 '17 at 12:10

There are two ways of adding package level documentation using javadoc:

package-info.java
- Only from 5.0
- Preferred way
- Can contain a package declaration, package annotations, package comments and Javadoc tags
package.html
- Any Java version
- Can not contain package declaration and/or package annotations

More details and examples are here. Which one to use: Javadoc: package.html or package-info.java

score 2 · Answer 5 · answered Sep 06 '10 at 11:05

2

Google found this as the first hit:

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#packagecomments

You just create a file named package.html in each package.

answered Sep 06 '10 at 11:05

duffymo

305,152
44
369
561

1

Where do you place `package-info.html`? – Danijel Oct 25 '13 at 13:48
I think they go in the package root. Make sense to try. Don't know how it's changed in three years since I answered this. – duffymo Oct 25 '13 at 16:39
@Danijel, We can't have subfolders in packages could we... – Pacerier Aug 15 '14 at 21:19

score 1 · Answer 6 · answered Sep 06 '10 at 11:05

1

By using a package.html file for your comments. Please see this document: How to Write Doc Comments for the Javadoc Tool.

answered Sep 06 '10 at 11:05

Carlos

2,503
26
29

score 1 · Answer 7 · answered Sep 06 '10 at 11:10

You can add documentation at package level.

From Sun documentation:

Typically package-info.java contains only a package declaration, preceded immediately by the annotations on the package. While the file could technically contain the source code for one or more package-private classes, it would be very bad form.

It is recommended that package-info.java, if it is present, take the place of package.html for javadoc and other similar documentation generation systems. If this file is present, the documentation generation tool should look for the package documentation comment immediately preceding the (possibly annotated) package declaration in package-info.java. In this way, package-info.java becomes the sole repository for package level annotations and documentation. If, in future, it becomes desirable to add any other package-level information, this file should prove a convenient home for this information.

How to add package level comments in Javadoc?

7 Answers7

Linked