Java Reference
In-Depth Information
the classes, methods, or fields in an application are not commented specifically for the
Javadoc
utility, default documentation will still be produced for such elements.
Formatting the Documentation
To create a Javadoc comment, begin with the characters
/**
. Although optional since
Java 1.4, a common practice is to include an asterisk as the first character of every sub-
sequent line within the comment. Another good practice is to indent the comment so
that it aligns with the code that is being documented. Lastly, close the comment with
the characters
*/
.
Javadoc comments should begin with a short description of the class or method.
Fields are rarely commented using Javadoc, unless they are declared
public stat-
ic final
(constants), in which case it is a good idea to supply a comment. A com-
ment can be several lines in length, and can even contain more than one paragraph. If
you want to break comments into paragraphs, then separate those paragraphs using the
<p>
tag. Comments can include several tags that indicate various details regarding the
method or class that is being commented. Javadoc tags begin with an ampersand
(@)
,
and some of the common tags are as follows:
@param: Name and description of a parameter
@return: What is returned from the method
@see: Reference to another piece of code
You may also include inline links within Javadoc to reference URLs. To include an
inline link, use the tag
{@link My Link}
, where
link
is the actual URL that you
want to point at and
My Link
is the text that you want to have appear. There are also
many other tags that can be used within Javadoc comments, including
{@literal}
,
{@code}
,
{@value org}
, and many others. For a complete listing, see the Javadoc
reference on the Oracle Technology Network website.
Executing the Tool
The
Javadoc
tool can also be run against entire packages or source. Simply pass a
package name to the
Javadoc
tool rather than individual source file names. For in-
stance, if an application includes a package named
org.juneau.beans
, all source
files within that package can be documented by running the tool as follows:
