Javadoc Documentation Generator - Java Software Solutions: Foundations of Program Design - page 698

Doc Comments
The document comments are subdivided into descriptions and tags. Descriptions
should provide an overview of the functionality of the explained code. Tags
address the specifics of the functionality such as code version (for classes or inter-
faces) or return types (for methods).
Javadoc processes code comments placed between /** , the beginning tag, and
*/ , the end tag. The comments are allowed to span multiple lines where each
line begins with a * character, which are, along with any white space before
them, discarded by the tool. These comments are allowed to contain HTML tags.
For example:
/**
* This is an <strong>example</strong> document comment.
*/
Comment placement should be considered carefully. The javadoc tool auto-
matically copies the first sentence from each doc to a summary at the top of
the HTML document. The sentence begins after any white space following the
* character and ends at the first period. The description that follows should
be concise and complete. Document comments are recognized only if they
are placed immediately before a class, constructor, method, interface, or field
declaration.
The use of HTML inside the description should be limited to proper comment
separation and display rather than styling. Javadoc automatically structures the
document using certain tags—for example, heading tags. Appropriate use of
paragraph or list tags (ordered/unordered) should provide satisfactory formatting.
Tags
Tags are included in a doc comment. Each tag must start on a separate line, hence
it must be preceded by the * character. Tags are case sensitive and begin with the
@ symbol.
Certain tags are required in some situations. The @param tag must be supplied
for every parameter and is used to describe the purpose of the parameter. The
@return tag must be supplied for every method that returns anything other than
void , to describe what the method returns. The @author class and the @version
tags are required for classes and interfaces only.
Figure I.1 lists the various tags used in javadoc comments.
Note the two different types of tags listed in Figure I.1. The block tags,
which begin with the @ symbol (e.g., @author ), must be placed in the tag section