How to add package level comments

I am using Check-Style, 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 Check-Style, but I don’t understand it.

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

How to add comments

I’m trying to add comments to post model. This is my comments_controller so far: class CommentsController < ApplicationController before_action :find_post def index @comments = @post.comments.order

How to add level2 predictors in multilevel regression (package nlme)

I have a question concerning multi level regression models in R, specifically how to add predictors for my level 2 measure. Please consider the following example (this is not a real dataset, so the

XML comments in NuGet package

How do I publish the xml-comments with my assemblies in a NuGet Package so that consumers can see class / method comments?

How do I add comments to package.json for npm install?

I’ve got a simple package.json file and I want to add a comment. Is there a way to do this, or are there any hacks to make this work? { name: My Project, version: 0.0.1, private: true, depe

How to add comments to my java application(standard way)

I like to add comments(class, method level) in my java based application(source files). i like to know if there is any standard way to add comments and also share some of the tools that can make some

Empty template for package-level Javadoc file

The Oracle page How to Write Doc Comments for the Javadoc Tool has a link to a Empty Template for Package-Level Doc Comment File which does not show the expected content of a basic ‘package.html’

How to add comments in PHP Eclipse?

How can I add comments in PHP eclipse? I’m trying by selecting few lines of code, then right click, On menu, Source and then I have tried all these options there general element comment, toggle c

How to add comments in Struts tags?

I have the following tag, how to add comments in it ? <s:select id=productPrice.product name=productPrice.product headerKey=0 headerValue=– Select Product — list=products listKey=id l

Package access level [duplicate]

This question is an exact duplicate of: Package accessibility for function and/or class 5 answers I’m wondering about how is it possible to set the package level access for a method in cpp. Con

Add .NET source documention on package/namespace level for processing with Doxygen

I use doxygen and XMl documentation comments to create an internal API documentation for our framework libaries. Doxygen creates a package per namespace. I wonder wheather its possible to add source

Answers

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.

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

  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

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.

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

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.

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