Documentation Comments | Core Java(TM) 2, Volume I--Fundamentals (7th Edition) (Core Series) (Core Series)

The JDK contains a very useful tool, called javadoc, that generates HTML documentation from your source files. In fact, the on-line API documentation that we described in Chapter 3 is simply the result of running javadoc on the source code of the standard Java library.

If you add comments that start with the special delimiter /** to your source code, you too can easily produce professional-looking documentation. This is a very nice scheme because it lets you keep your code and documentation in one place. If you put your documentation into a separate file, then you probably know that the code and comments tend to diverge over time. But because the documentation comments are in the same file as the source code, it is an easy matter to update both and run javadoc again.

Comment Insertion

The javadoc utility extracts information for the following items:

Packages
Public classes and interfaces
Public and protected methods
Public and protected fields

Protected features are introduced in Chapter 5, interfaces in Chapter 6.

You can (and should) supply a comment for each of these features. Each comment is placed immediately above the feature it describes. A comment starts with a /** and ends with a */.

Each /** . . . */ documentation comment contains free-form text followed by tags. A tag starts with an @, such as @author or @param.

The first sentence of the free-form text should be a summary statement. The javadoc utility automatically generates summary pages that extract these sentences.

In the free-form text, you can use HTML modifiers such as <em>...</em> for emphasis, <code>...</code> for a monospaced "typewriter" font, <strong>...</strong> for strong emphasis, and even <img ...> to include an image. You should, however, stay away from headings <h1> or rules <hr> because they can interfere with the formatting of the document.

NOTE

If your comments contain links to other files such as images (for example, diagrams or images of user interface components), place those files into subdirectories named doc-files. The javadoc utility will copy these directories and the files in them from the source directory to the documentation directory.

Class Comments

The class comment must be placed after any import statements, directly before the class definition.

Here is an example of a class comment:

 /**    A <code>Card</code> object represents a playing card, such    as "Queen of Hearts". A card has a suit (Diamond, Heart,    Spade or Club) and a value (1 = Ace, 2 . . . 10, 11 = Jack,    12 = Queen, 13 = King). */ public class Card {    . . . }

NOTE

Many programmers start each line of a documentation with an asterisk, like this:

 /**  * A <code>Card</code> object represents a playing card, such  * as "Queen of Hearts". A card has a suit (Diamond, Heart,  * Spade or Club) and a value (1 = Ace, 2 . . . 10, 11 = Jack,  * 12 = Queen, 13 = King)  */

We don't do this because it discourages programmers from updating the comments. Nobody likes rearranging the * characters when the line breaks change. However, some text editors have a mode that takes care of this drudgery. If you know that all future maintainers of your code will use such a text editor, you may want to add the border to make the comment stand out.

Method Comments

Each method comment must immediately precede the method that it describes. In addition to the general-purpose tags, you can use the following tags:

@param variable description

This tag adds an entry to the "parameters" section of the current method. The description can span multiple lines and can use HTML tags. All @param tags for one method must be kept together.

@return description

This tag adds a "returns" section to the current method. The description can span multiple lines and can use HTML tags.

@throws class description

This tag adds a note that this method may throw an exception. Exceptions are the topic of Chapter 11.

Here is an example of a method comment:

 /**    Raises the salary of an employee.    @param byPercent the percentage by which to raise the salary       (e.g. 10 = 10%)    @return the amount of the raise */ public double raiseSalary(double byPercent) {    double raise = salary * byPercent / 100;    salary += raise;    return raise; }

Field Comments

You only need to document public fields generally that means static constants. For example,

 /**    The "Hearts" card suit */ public static final int HEARTS = 1;

General Comments

The following tags can be used in class documentation comments.

@author name

This tag makes an "author" entry. You can have multiple @author tags, one for each author.

@version text

This tag makes a "version" entry. The text can be any description of the current version.

The following tags can be used in all documentation comments.

@since text

This tag makes a "since" entry. The text can be any description of the version that introduced this feature. For example, @since version 1.7.1

@deprecated text

This tag adds a comment that the class, method, or variable should no longer be used. The text should suggest a replacement. For example,

 @deprecated Use <code>setVisible(true)</code> instead

You can use hyperlinks to other relevant parts of the javadoc documentation, or to external documents, with the @see and @link tags.

@see reference

This tag adds a hyperlink in the "see also" section. It can be used with both classes and methods. Here, reference can be one of the following:

package.class#feature label
<a href="...">label</a>
"text"

The first case is the most useful. You supply the name of a class, method, or variable, and javadoc inserts a hyperlink to the documentation. For example,

 @see com.horstmann.corejava.Employee#raiseSalary(double)

makes a link to the raiseSalary(double) method in the com.horstmann.corejava.Employee class. You can omit the name of the package or both the package and class name. Then, the feature will be located in the current package or class.

Note that you must use a #, not a period, to separate the class from the method or variable name. The Java compiler itself is highly skilled in guessing the various meanings of the period character, as separator between packages, subpackages, classes, inner classes, and methods and variables. But the javadoc utility isn't quite as clever, and you have to help it along.

If the @see tag is followed by a < character, then you need to specify a hyperlink. You can link to any URL you like. For example,

 @see <a href="www.horstmann.com/corejava.html">The Core Java home page</a>

In each of these cases, you can specify an optional label that will appear as the link anchor. If you omit the label, then the user will see the target code name or URL as the anchor.

If the @see tag is followed by a " character, then the text is displayed in the "see also" section. For example,

 @see "Core Java 2 volume 2"

You can add multiple @see tags for one feature, but you must keep them all together.

If you like, you can place hyperlinks to other classes or methods anywhere in any of your comments. You insert a special tag of the form {@link package.class#feature label} anywhere in a comment. The feature description follows the same rules as for the @see tag.

Package and Overview Comments

You place class, method, and variable comments directly into the Java source files, delimited by /** . . . */ documentation comments. However, to generate package comments, you need to add a file named package.html in each package directory. All text between the tags <BODY>...</BODY> is extracted.

You can also supply an overview comment for all source files. Place it in a file called overview.html, located in the parent directory that contains all the source files. All text between the tags <BODY>...</BODY> is extracted. This comment is displayed when the user selects "Overview" from the navigation bar.

Comment Extraction

Here, docDirectory is the name of the directory where you want the HTML files to go. Follow these steps:

Change to the directory that contains the source files you want to document. If you have nested packages to document, such as com.horstmann.corejava, you must be working in the directory that contains the subdirectory com. (This is the directory that contains the overview.html file if you supplied one.)

Run the command

javadoc -d docDirectory nameOfPackage

for a single package. Or run

javadoc -d docDirectory nameOfPackage₁ nameOfPackage₂...

to document multiple packages. If your files are in the default package, then instead run

javadoc -d docDirectory *.java

If you omit the -d docDirectory option, then the HTML files are extracted to the current directory. That can get messy, and we don't recommend it.

The javadoc program can be fine-tuned by numerous command-line options. For example, you can use the -author and -version options to include the @author and @version tags in the documentation. (By default, they are omitted.) Another useful option is -link, to include hyperlinks to standard classes. For example, if you use the command

 javadoc -link http://java.sun.com/j2se/5.0/docs/api *.java

then all standard library classes are automatically linked to the documentation on the Sun web site.

For additional options, we refer you to the on-line documentation of the javadoc utility at http://java.sun.com/j2se/javadoc.

NOTE

If you require further customization, for example, to produce documentation in a format other than HTML, then you can supply your own doclet to generate the output in any form you desire. Clearly, this is a specialized need, and we refer you to the on-line documentation for details on doclets at http://java.sun.com/j2se/javadoc.

TIP

A useful doclet is DocCheck, at http://java.sun.com/j2se/javadoc/doccheck/. It scans a set of source files for missing documentation comments.