This page provides brief documentation for the basics of javadoc comments and the small subset of javadoc tags used in CSC 142. The contents have been excerpted from http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html on the java.sun.com web site.
You can include documentation comments in the source code, ahead of declarations for any entity (classes, interfaces, methods, constructors, or fields). These are also known as Javadoc comments. A doc comment consists of the characters between the characters /** that begin the comment and the characters */ that end it. The text can continue onto multiple lines.
/**
* This is the typical format of a simple documentation comment.
*/
To save space you can put a comment on one line:
/** This comment takes up only one line. */
Placement of comments - Documentation comments are recognized only when placed immediately before class, interface, constructor, method, or field declarations -- see the class example, method example, and field example. Documentation comments placed in the body of a method are ignored. Only one documentation comment per declaration statement is recognized by the Javadoc tool. A common mistake is to put an import statement between the class comment and the class declaration. Avoid this, as Javadoc will ignore the class comment.
/**
* This is the class comment for the class Whatever.
*/
import com.sun; // MISTAKE - Important not to put import statement here
public class Whatever { }
A comment is a description followed by tags - The description begins after the starting delimiter /** and continues until the tag section. The tag section starts with the first character @ that begins a line (ignoring leading asterisks, white space and comment separator). The description cannot continue after the tag section begins. There can be any number of tags -- some types of tags can be repeated while others cannot. This @param starts the tag section:
/**
* This is a doc comment.
* @param width horizontal width of the rectangle
* @param height vertical height of the rectangle
*/
Leading asterisks - When javadoc parses a doc comment, leading asterisk (*) characters on each line are discarded; blanks and tabs preceding the initial asterisk (*) characters are also discarded. If you omit the leading asterisk on a line, all leading white space is removed. Therefore, you should not omit leading asterisks if you want leading white space to kept, such as when indenting sample code with the <pre> tag. Without leading asterisks, the indents are lost in the generated documents, since the leading white space is removed.
First sentence - The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag. Javadoc copies this first sentence to the member summary at the top of the HTML page.
This section provides the syntax for four basic Javadoc tags. Javadoc parses special tags when they are embedded within a Java doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an "at" sign (@) and are case-sensitive -- they must be typed with the uppercase and lowercase letters as shown. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk) or it is treated as normal text. By convention, tags with the same name are grouped together.
The tags described here are:
Class documentation tags: @author @version
Method/Constructor tags: @param @return
Adds an "Author" entry with the specified name-text to the generated docs when the -author option is used. A doc comment may contain multiple @author tags. You can specify one name per @author tag or multiple names per tag. In the former case, Javadoc inserts a comma (,) and space between names.
Adds a "Version" subheading with the specified version-text to the generated docs when the -version option is used. The text has no special internal structure. A doc comment may contain at most one @version tag.
@param parameter-name description
Adds a parameter to the "Parameters" section. The description may be continued on the next line.
Adds a "Returns" section with the description text. This text should describe the return type and permissible range of values.
An example of a class comment:
/**
* A class representing a rectangle shape.
*
* @author Ben Dugan
* @version 4/16/2001
*/
public class Rectangle implements Shape {
...
}
An example of a field comment:
/**
* the x coordinate of the upper left corner of the window
*/
int x = 0;
...
An example of a method comment:
/**
* Computes the straight-line distance of the move
* rounded to the nearest unit.
*
* @param deltaX offset in the X direction.
* @param deltaY offset in the Y direction.
* @return the straight-line distance as an int
*/
public int distance(int deltaX, int deltaY) {
...
}
Last Updated 10/10/2005
by Vince Offenback