The ABCs of Programming - Java 6 - page 38

The first way to add a comment to a program is to precede it with two slash characters
(“//”). Everything from the slashes to the end of the line is considered a comment and is
disregarded by a Java compiler, as in the following statement:

int creditHours = 3; // set up credit hours for course

If you need to make a comment that takes up more than one line, you can begin it with
the text “/*” and end it with the text “*/”. Everything between these two delimiters is
considered a comment, as in the following:

/* This program occasionally deletes all files on
your hard drive and renders it completely unusable
when you press the Save button. */

The final type of comment is meant to be computer-readable as well as human-readable.
If you begin a comment with the text “/**” (instead of “/*”) and end it with “*/”, the
comment is interpreted to be official documentation on how the class and its methods
work.

This kind of comment then can be read by utilities such as the javadoc tool included
with the JDK. The javadoc program uses official comments to create a set of Hypertext
Markup Language (HTML) records that document the program, its class hierarchy, and
its methods. More information is available on javadoc in Appendix B, “Programming
with the Java Development Kit.”

TIP

All the official documentation on Java's class library comes from
javadoc -style comments. You can view current Java documentation
on the Web at http://java.sun.com/javase/6/docs/api.

Literals
In addition to variables, you can work with values as literals in a Java statement. A lit-
eral is any number, text, or other information that directly represents a value.

The following assignment statement uses a literal:

int year = 2007;

The literal is 2007 because it directly represents the integer value 2007. Numbers, char-
acters, and strings all are examples of literals.