Java Reference
In-Depth Information
For example, if you were creating a class to provide a network connection to your server,
you might call the class
NetworkConnection
. There is no point in having a Javadoc comment
that states that this class provides “a network connection”—the user already knows that.
Instead, you might consider specifying that the class provides “a connection to the database
server over the network through which remote access to the database functions can be used.”
■
Caution
You should not write any implementation-specific details in your Javadoc comments.
Where to Put your Javadoc Comments
In theory, Javadoc comments can go anywhere in your source code. However, the Javadoc
application will only include comments in specific locations:
•
Class comments should appear immediately before the class declaration ( Javadoc cur-
rently allows the comments to appear anywhere before the class declaration, even
before the package declaration, but this behavior should not be relied on).
•
Class and instance variable comments should appear immediately before the class or
instance variable to which they belong.
•
Method comments should appear immediately before the method signature.
The Javadoc tool will ignore Javadoc comments in any other locations entirely. If you want
to put a comment inside a method, for example, there's no point in making it a Javadoc com-
ment, as it won't appear in any generated API. Just use an implementation comment.
Formatting Codes and Special Tags
Javadoc comments can contain any HTML markup tags. Commonly used tags are shown in
Table 2-4.
Table 2-4.
Commonly Used HTML Tags
Tag
End Tag
Description
<code>
</code>
Text between these two tags will appear in monospaced font in the
HTML output. This is usually designed for short words or phrases.
<pre>
</pre>
Text between these two tags will appear in monospaced font in the
HTML output, maintaining your indentation. This is usually used for
example code.
<ul>
</ul>
Denotes the start and end of an unordered list (not numbered).
<ol>
</ol>
Denotes the start and end of an ordered list (numbered).
<li>
Denotes the start of a list item within either an unordered or an
ordered list.
<p>
Denotes the start of a new paragraph.
