Java Reference
In-Depth Information
19.1. The Anatomy of a Doc Comment
Doc comments start with the three characters
/**
and continue until the
next
*/
. Each doc comment describes the identifier whose declaration
immediately follows. Leading
*
characters are ignored on doc comment
lines, as are whitespace characters preceding a leading
*
. The first sen-
tence of the comment is the summary for the identifier; "sentence"
means all text up to the first period with following whitespace. Consider
the doc comment:
/**
* Do what the invoker intends. "Intention" is defined by
* an analysis of past behavior as described in ISO 4074-6.
*/
public void dwim() throws IntentUnknownException;
The summary for the method
dwim
will be "Do what the invoker intends."
Your first sentence in a doc comment should be a good summary.
HTML
tags are often embedded in doc comments as formatting directives
or cross-reference links to other documentation. You can use almost any
standard
HTML
tag. Be careful when using the header tags
<h1>
,
<h2
>, and
so on, because they can disrupt the structure of the overall documenta-
tionhowever, they are usually safe to use within class and package docu-
mentation. To insert the character
<
,
>
, or
&
you should use
<
,
>
, or
&
, respectively. If you must have an
@
at the beginning of a line, use
@
otherwise, an
@
is assumed to start a doc comment tag.
Only doc comments that immediately precede a class, interface, method,
or field are processed. If anything besides whitespace, comments, or an-
notations are between a doc comment and what it describes, the doc
comment will be ignored. For example, if you put a doc comment at the
top of a file with a
package
or
import
statement between the doc comment
and the
class
, the doc comment will not be used. Doc comments apply to
