Java supports three types of comments. The first type is a single-line comment, which begins with the characters // and continues until the end of the current line. For example:
int i = 0; // initialize the loop variable
The second kind of comment is a multiline comment. It begins with the characters /* and continues, over any number of lines, until the characters */. Any text between the /* and the */ is ignored by the Java compiler. Although this style of comment is typically used for multiline comments, it can also be used for single-line comments. This type of comment cannot be nested (i.e., one /* */ comment cannot appear within another one). When writing multiline comments, programmers often use extra * characters to make the comments stand out. Here is a typical multiline comment:
/* * Step 4: Print static methods, both public and protected, * but don't list deprecated ones. */
The third type of comment is a special case of the second. If a comment begins with /**, it is regarded as a special doc comment. Like regular multiline comments, doc comments end with */ and cannot be nested. When you write a Java class you expect other programmers to use, use doc comments to embed documentation about the class and each of its methods directly into the source code. A program named javadoc extracts these comments and processes them to create online documentation for your class. A doc comment can contain HTML tags and can use additional syntax understood by javadoc. For example:
/** * Display a list of classes, many to a line. * * @param classes The classes to display * @return <tt>true</tt> on success, * <tt>false</tt> on failure. * @author David Flanagan */
See Chapter 7, "Java Programming and Documentation Conventions", for more information on the doc-comment syntax and Chapter 8, "Java Development Tools", for more information on the javadoc program.
Copyright © 2001 O'Reilly & Associates. All rights reserved.