produced separately, although they can be cross-referenced by the doc comment, as you will soon see.[1]

[1] This distinction is blurring and, for better or worse, documentation comments are being

used to define full specifications.

The procedure for generating documentation from the doc comments varies among development
environments. One common procedure is to run the javadoc command on the packages or types; hence, the
generated documentation is often called javadoc.

This chapter teaches what can go into documentation comments and how the contents are interpreted. You
will also learn about features that are, strictly speaking, outside the language but are conventions for creating
the generated documentation, such as overall package documentation and the location for images and other
resources. Your development environment may not use these details in precisely the same way as javadoc
but it is likely to, and if not will usually have an analogous replacement. These features are covered in the
section "External Conventions" on page 496.

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 sentence 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

,

, and so on, because they can disrupt the structure of the overall documentationhowever, they are usually
safe to use within class and package documentation. 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 annotations 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 all fields declared in a single statement, so declaring multiple fields in a single statement is
usually avoided where doc comments are used.