4.2 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 because you can still wrap block comments around large chunks of code during development.

By convention, a block comment beginning with /** indicates a special "doc comment." A doc comment is commentary that is extracted by automated documentation generators, such as Sun's javadoc program that comes with the Java Development Kit. 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 class documentation 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 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. For example, a variable declaration can contain only a @see tag. Table 4.1 summarizes the tags used in doc comments.