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
Block comments have both a beginning and end sequence and can cover
large ranges of text. However, they cannot be “nested,” meaning that you
can’t have a block comment inside of a block comment without the compiler
getting confused. Single-line comments have only a start sequence and 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 block comments, so you can still comment out larger
chunks of code in which they are nested.
A block comment beginning with /**
indicates a special
doccomment. A
doc comment is designed to be extracted by automated documentation
generators, such as the JDK’s javadoc program. A
doc comment is terminated by the next */
, just as with a regular block comment.
Within the doc comment, lines beginning with @
are interpreted as
special instructions for the documentation generator, giving it
information about the source code. By convention, each line of a doc
comment begins with a *
, as shown in
the following example, but this is optional. Any leading spacing and the
*
on each line are ignored:
/**
* 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 2006
*/
class
Potato
{
javadoc creates HTML documentation for
classes by reading the source code and pulling out the embedded comments
and @
tags. In this example, the tags
cause author and version information to be presented in the class
documentation. The @see
tags produce
hypertext links to the related 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 fact that a method is deprecated is noted in the
compiled class file so a warning message can be generated whenever you
use a deprecated feature in your code (even if the source isn’t
available).
Doc comments can appear above class, method, and variable
definitions, but some tags may not be applicable to all of these. For
example, the @exception
tag can only
be applied to methods. Table 4-1
summarizes the tags used in doc comments.
Table 4-1. Doc comment tags
Tag | Description | Applies to |
---|---|---|
Associated class name | Class, method, or variable | |
Author name | Class | |
Version string | Class | |
Parameter name and description | Method | |
Description of return value | Method | |
Exception name and description | Method | |
Declares an item to be obsolete | Class, method, or variable | |
Notes API version when item was added | Variable |
Javadoc tags in doc comments represent metadata about the source code;
that is, they add descriptive information about the structure or
contents of the code that is not, strictly speaking, part of the
application. Some additional tools extend the concept of Javadoc-style
tags to include other kinds of metadata about Java programs that are
carried with the compiled code and can more readily be used by the
application to affect its compilation or runtime behavior. The Java
annotations facility provides a more formal and
extensible way to add metadata to Java classes, methods, and
variables. We’ll talk about annotations in Chapter 7. However, we should mention that there
is a @deprecated
annotation that
has the same meaning as that of the Javadoc tag of the same name, and
you may prefer to use that.
Get Learning Java, 4th Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.