Big Java, 4th Edition

Appendix H. javadoc Summary

Setting Documentation Comments in Source

A documentation comment is delimited by /** and */. You can comment

• Classes

• Methods

• Instance variables

Each comment is placed immediately above the feature it documents.

Each /** ... */ documentation comment contains introductory text followed by tagged documentation. A tag starts with an @ character, such as @author or @param. Tags are summarized in Table 1. The first sentence of the introductory text should be a summary statement. The javadoc utility automatically generates summary pages that extract these sentences.

Table H.1. Common javadoc Tags

Tag	Description
@param parameter explanation	A parameter of a method. Use a separate tag for each parameter.
@return explanation	The return value of a method.
@throws exceptionType explanation	An exception that a method may throw. Use a separate tag for each exception.
@deprecated	A feature that remains for compatibility but that should not be used for new code.
@see packageName.ClassName @see packageName.ClassName #methodName(Type1, Type2, ...) @see packageName.ClassName#variableName	A reference to a related documentation entry.
@author	The author of a class or interface. Use a separate tag for each author.
@version	The version of a class or interface.

You can use HTML tags such as em for emphasis, code for a monospaced font, img for images, ul for bulleted lists, and so on.

Here is a typical example. The summary sentence (in color) will be included with the method summary.

/**
   Withdraws money ...