How to add package level comments in Javadoc? [dup

Question

This question already has answers here:

How Do I Document Packages in Java? (3 answers)

Closed 2 years ago.

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?

Answer 1

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

Answer 2

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.

Answer 3

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

Answer 4

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

1. package-info.java
   • Only from 5.0
   • Preferred way
   • Can contain a package declaration, package annotations, package comments and Javadoc tags
2. 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

Answer 5

1. Create a file package-info.java in your package to document
2. Add the package descriptor
3. 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

Answer 6

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.