Java supports both C-style block comments
delimited by /*
and */
and C++
- style line comments indicated by //
:
/* This is a multiline comment. */ // This is a single-line comment // and so // is this
As
in C, block comments can’t be nested.
Single-line comments are delimited by the end of a
line; extra //
indicators inside a single line
have no effect. Line comments are useful for short comments within
methods; they don’t conflict with wrapping block comment
indicators around large chunks of code during development.
By convention,
a block comment beginning with
/**
indicates a special doc
comment
. A doc comment is designed to be
extracted by automated documentation generators,
such as the DSK’s javadoc
program. A doc
comment is terminated by the next */
, just as with
a regular block comment. Leading spacing up to a *
on each line is ignored; lines beginning with @
are interpreted as special tags for the documentation generator.
/** * I think this class is possibly the most amazing thing you will * ever see. Let me tell you about my own personal vision and * motivation in creating it. * <p> * It all began when I was a small child, growing up on the * streets of Idaho. Potatoes were the rage, and life was good... * * @see PotatoPeeler * @see PotatoMasher * @author John 'Spuds' Smith * @version 1.00, 19 Dec 1996 */
javadoc
creates
HTML format documentation of classes by reading the source code and
the embedded comments. The author and version information is
presented in the output, and the @see
tags make
hypertext links to the appropriate
class documentation. The compiler also looks at the doc comments; in
particular, it is interested in
the @deprecated
tag, which means that the method has been declared obsolete and
should be avoided in new programs. The compiler generates a warning
message whenever it sees the usage of a deprecated feature in your
code.
Doc
comments can appear above class, method, and variable definitions,
but some tags may not be applicable to all of these. For example, a
variable declaration can contain only a @see
tag.
Table 4.1 summarizes the tags used in doc
comments.
Table 4-1. Doc Comment Tags
Tag |
Description |
Applies to |
---|---|---|
@see |
Associated class name |
Class, method, or variable |
@author |
Author name |
Class |
@version |
Version string |
Class |
@param |
Parameter name and description |
Method |
@return |
Description of return value |
Method |
@exception |
Exception name and description |
Method |
@deprecated |
Declares an item to be obsolete |