Java Reference
In-Depth Information
The descriptive material in a doc comment can contain simple HTML markup tags,
such as
<i>
for emphasis,
<code>
for class, method, and field names, and
<pre>
for
multiline code examples. It can also contain
<p>
tags to break the description into
separate paragraphs and
<ul>
,
<li>
, and related tags to display bulleted lists and
similar structures. Remember, however, that the material you write is embedded
within a larger, more complex HTML document. For this reason, doc comments
should not contain major structural HTML tags, such as
<h2>
or
<hr>
, that might
interfere with the structure of the larger document.
Avoid the use of the
<a>
tag to include hyperlinks or cross-references in your doc
comments. Instead, use the special
{@link}
doc-comment tag, which, unlike the
other doc-comment tags, can appear anywhere within a doc comment. As described
in the next section, the
{@link}
tag allows you to specify hyperlinks to other classes,
interfaces, methods, and fields without knowing the HTML-structuring conven‐
tions and filenames used by
javadoc
.
If you want to include an image in a doc comment, place the image file in a
doc-iles
subdirectory of the source code directory. Give the image the same name as the
class, with an integer suffix. For example, the second image that appears in the doc
comment for a class named
Circle
can be included with this HTML tag:
<
img
src
=
"doc-files/Circle-2.gif"
>
Because the lines of a doc comment are embedded within a Java comment, any lead‐
ing spaces and asterisks (
*
) are stripped from each line of the comment before pro‐
cessing. Thus, you don't need to worry about the asterisks appearing in the gener‐
ated documentation or about the indentation of the comment affecting the indenta‐
tion of code examples included within the comment with a
<pre>
tag.
Doc-Comment Tags
The
javadoc
program recognizes a number of special tags, each of which begins
with an
@
character. These doc-comment tags allow you to encode specific informa‐
tion into your comments in a standardized way, and they allow
javadoc
to choose
the appropriate output format for that information. For example, the
@param
tag lets
you specify the name and meaning of a single parameter for a method.
javadoc
can
extract this information and display it using an HTML
<dl>
list, an HTML
<table>
,
or however it sees fit.
The following doc-comment tags are recognized by
javadoc
; a doc comment
should typically use these tags in the order listed here:
@author
name
Adds an “Author:” entry that contains the specified name. This tag should be
used for every class or interface definition but must not be used for individual
methods and fields. If a class has multiple authors, use multiple
@author
tags
on adjacent lines. For example:
