How to add package level comments in Javadoc? [duplicate]

Question

This question already has an answer here:

• How Do I Document Packages in Java? 3 answers

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

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 2

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 3

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 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

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.

Answer 6

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

Answer 7

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.