Section 4.2. Comments

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

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 including them.

4.2.1. Javadoc Comments

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 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
@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
@since	Notes API version when item was added	Variable

4.2.1.1 Javadoc as metadata

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. In the past, some additional tools have extended the concept of Javadoc-style tags to include other kinds of metadata about Java programs. Java 5.0 introduced a new annotations facility that 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 an @deprecated annotation that has the same meaning as that of the Javadoc tag of the same name. Users of Java 5.0 will likely prefer it to the Javadoc form.