Java Reference
In-Depth Information
5.5.3
There's more to Javadoc than just documenting the types and names of classes,
methods, and arguments. A developer can annotate or supplement the docu-
mentation by placing specially formatted comments in his or her code.
A Javadoc comment begins with the C-style open comment plus at least
one more asterisk. It ends with a C-style close comment. In other words:
Javadoc Comments
/* This is a C-style comment, but it
is _not_ a Javadoc comment. */
/** This is a C-style comment, but it
is also a Javadoc comment. */
This isn't a part of the Java programming language. It is merely a lexical hack
to allow the
javadoc
program to recognize a comment it should pick up and
process. Javadoc is fairly intelligent about where to place the text extracted from
a Javadoc comment. For example, a Javadoc comment placed just before the
start of a class will appear in the class summary on the package page and at the
top of the class detail page. A Javadoc comment placed just before a method
will appear in the method's box on the class detail page, and so on.
We encourage you to discover for yourself the relationship between
Javadoc comments and the output of the standard doclet. Use it. Experiment.
Or, you can go and read the official Sun Microsystems documentation on
Javadoc.
5
That's your choice.
Since comment text is extracted and placed into certain positions in an
HTML document, you may use HTML tags in your comments to affect how
they are rendered. Be aware that when you do so, you may get unexpected
results if you use any custom doclets.
There's more to it than that, however. There are a number of macros that
you can place in Javadoc comments to mark data of particular significance. For
example,
@author
should appear just before the name of the author of a
particular piece of code.
These
at-tags
must appear after all descriptive text in a Javadoc comment.
6
A tag must be at the beginning of a line within the comment (ignoring any
5.
http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html
6. The exception is embedded tags, which we will discuss in a moment.
