Java Reference
In-Depth Information
List of Block and Inline Tags
Not all tags can be used for the documentation comment in all contexts. Table
B-1
has the list of all block tags and
inline tags, and the contexts in which they can be used.
Table B-1.
List of Block and Inline Tags, and the Contexts in Which They Can Be Used
Tag
Overview
Package
Class, Interface,
Enum, and Annotation
Field
Constructor
and Method
@author
Yes
Yes
Yes
No
No
@deprecated
No
No
Yes
Yes
Yes
@exception
No
No
No
No
Yes
@param
No
No
No
No
Yes
@return
No
No
No
No
Yes (Methods only)
@see
Yes
Yes
Yes
Yes
Yes
@serial
No
Yes
Yes
Yes
No
@serialData
No
No
No
No
Yes (Methods only)
@serialField
No
No
No
Yes
No
@since
Yes
Yes
Yes
Yes
Yes
@throws
No
No
No
No
Yes
@version
Yes
Yes
Yes
No
No
{@code}
Yes
Yes
Yes
Yes
Yes
{@docRoot}
Yes
Yes
Yes
Yes
Yes
{@inheritDoc}
No
No
No
No
Yes (Methods only)
{@link}
Yes
Yes
Yes
Yes
Yes
{@linkplain}
Yes
Yes
Yes
Yes
Yes
{@literal}
Yes
Yes
Yes
Yes
Yes
{@value}
No
No
No
Yes
No
The Overview column in the table may not be obvious, because there is no such construct as “overview” in the
Java programming language. The
javadoc
tool lets you add documentation comments for the entire application
in one place, which is called an overview comment. The overview comment is displayed on the overview page
that is generated by the tool. I will discuss an example of how to include an overview comment in the generated
documentation later. The following sections will describe the tags in brief.
@author <author-name(s)>
The
@author
tag adds the author name or names under the Author section in the documentation. A documentation
comment may contain multiple
@author
tags. If you have multiple author names, you can use only one
@author
tag to specify
all author names or you can use a separate
@author
tag to specify each author name. If you use multiple
@author
tags, all
author names will be concatenated using a locale-specific separator and placed under one Author entry. Table
B-2
shows
the effects of using one and multiple
@author
tags. Note that the table shows only the Author entry from the generated text.
