How to add package level comments.

Question

Hi All,

I am using check-style, FindBug 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 am not able to understand it.

Could some one help me in writing a package level comment in java.

-- Thanks,
-- Anil Kumar.C

Answer 1

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 2

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

Answer 3

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

Thanks emory for pointing to this link: http://java.sun.com/docs/books/jls/third_edition/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 4

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 5

Package-level javadoc comments are placed in a file named package-info.java inside the pacakge 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;

Edit: This is documented here: http://download.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#packagecomment

Answer 6

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.