Java Reference
In-Depth Information
ment. When the comment was done, you ended the comment with
*/
. The compiler ignored
anything between the two. There was no nesting of comments (multiple instances of
/*
would
Some time later, it was observed that there are really two kinds of comments that you want
to put into your code. There are long comments, often spanning multiple lines, which are just
fine for marking with the existing comment delimiters. But there are also times when a pro-
grammer just wants to make a short comment at the end of a line or on a single line, and the
notion of having a comment delimiter that marked everything from the comment sign to the
end of the line as a comment was born. C++ was the first language I used that had this kind of
comment, where anything from a
//
until the end of the line was seen as a comment; standard
C adopted this form of comment, as did Java. Soon, the type of comment that started with
/*
and ended with
*/
was known as a
block comment
, whereas those that started with
//
and
ended with a line break were known as
line comments
.
Java added a third kind of comment, called
documentation comments
. These are like a block
comment, but in addition to being ignored by the compiler, these comments are designed to
be read by a separate tool, Javadoc. This tool then uses these comments to produce document-
ation for the code containing the comment. The tool that parses these comments was written
when Java was seen as a programming environment for the Web, so the output of the tool is a
set of
.html
files designed to be read as hypertext in a standard web browser.
Documentation comments begin with the characters
/**
and end with the characters
*/
. This
makes them a variant of block comments, and like block comments, multiple lines of text can
appear between the delimiters. By convention, the beginning of every line in a documentation
comment begins with the
*
character, but this is just convention. You can start the interven-
ing lines with no special character and things will be just fine. But it isn't a bad convention,
because it will remind you that those intervening lines are comments. Most IDEs (which is to
say, both Eclipse and Netbeans) will automatically start a line in a documentation comment
with a
*
.
Unlike standard comments, documentation comments can only appear in certain places in a
source file. You may have a documentation comment prior to the declaration of a class or an
interface or prior to the declaration of a method or a field in a class, but such comments will
be ignored if they are placed in the body of a method. This is a reflection of the purpose of
these comments. They are meant to document your interfaces, classes, and methods, but not
the details of the implementations of those classes and methods. They are meant to give you
a mechanism to describe what these constructs do, not how they do it. This doesn't mean that
