Creating Documentation with Javadoc - Java Programming: Comprehensive Concepts and Techniques - page 952

Placement of Doc Comments
In order for the Javadoc command to read the doc comments and convert them to
program documentation, you must place doc comments directly above the package,
class, or method declaration. For example, if you want to document a method named
getCost(), you must place the doc comments in the code just before the getCost()
method header. That way, Javadoc can associate the description and tags with the
correct method. If you place other code between the doc comment and the method
header, the documentation will not display the description and may generate an error.

Within the beginning and ending marks, each doc comment is made up of two parts: a description
followed by block tags. A description is a short summary or definition of the object, as shown in line
12 of Figure E-4 on the previous page. A tag , or block tag , is an HTML notation that uses a keyword to
send information to an HTML file, as shown in lines 13 and 14 of Figure E-4.

Javadoc Tags

A Javadoc tag begins with the @ sign, followed by a keyword that represents a special reference
understood by Javadoc. A tag provides structure that Javadoc can parse into text, font styles, and links
in the HTML files generated as program documentation.
Tags come in two types: stand-alone tags and inline tags. Stand-alone tags can be placed only in
the tag section that follows the description in a doc comment. These tags are not set off with curly
braces. Inline tags can be placed anywhere in the comment description or in the comments for stand-
alone tags. Inline tags are set off with curly braces. Table E-1 lists commonly used Javadoc tags.

Table E-1 Commonly Used Javadoc Tags

TAG NAME DOCUMENTATION RESULT SYNTAX

@author Adds an Author section with the specified name to the @author name-text

generated documents when the author parameter is used.
A doc comment may contain multiple @author tags.

@deprecated Adds a comment indicating that this API is deprecated and @deprecated

should no longer be used. deprecated-text

@exception Is a synonym for @throws. @exception class-name

description

{@link} Inserts a link that points to the specified name. This tag {@link name }

accepts the same syntax as the @see tag, but generates an
inline link. This tag begins and ends with curly braces to
separate it from the rest of the inline text.

@param Adds a Parameter section that lists and defines method @param parameter-

parameters. name description

@return Adds a Returns section with the description text. This text @return description

should describe the return type and permissible range of values.