Comments

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.

Javadoc Comments

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.

Here’s an example:

/**  
 * 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

Class, method, or variable

Get Learning Java 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.