Programs, Data, Variables, and Calculation - Beginning Java - page 80

PROGRAM COMMENTS
I have been adding comments in all the examples so far, so you already know that everything following //
in a line is ignored by the compiler (except when the // appears in a character string between double quotes
of course). Another use for // is to change lines of codes into comments so that they aren't executed — to
“comment them out” in other words. If you want to remove some code from a program temporarily, you just
add // at the beginning of each line that you want to eliminate. Removing the // later restores the line of
code.
It is often convenient to include multiple lines of comment in a program — for example, at the beginning
of a method to explain what it does. An alternative to using // at the beginning of each line in a block of
comments is to put /* at the beginning of the first comment line and */ at the end of the last comment line.
Everything between the /* and the */ is ignored. By this means you can annotate your programs, like this
for example:
/***************************************
* This is a long explanation of *
* some particularly important *
* aspect of program operation. *
***************************************/
Here I have used asterisks to highlight the comment. Of course, you can frame blocks like this in any way
that you like, or even not at all, just so long as there is /* at the beginning and */ at the end.
Documentation Comments
You can also include comments in a program that are intended to produce separate documentation for the
program. These are called documentation comments . A program called javadoc processes the documenta-
tion comments in the source code for a program to generate separate documentation for the code. All the
documentation that you get with the SDK is produced in this way.
The documentation that is generated by javadoc is in the form of HTML web pages that can be viewed
using a browser such as Firefox or Internet Explorer. A full discussion of documentation comments is out-
side the scope of this topic — not because they are difficult; they aren't. However, it would need a lot of
pages to cover them properly, and there are already a lot of pages in the topic. Here I just describe them
sufficiently so that you will recognize documentation comments when you see them.
A documentation comment begins with /** and ends with */ . An example of a simple documentation
comment is the following:
/**
* This is a documentation comment.
*/
Any asterisks at the beginning of each line in a documentation comment are ignored, as are any spaces
preceding the first asterisk.
A documentation comment can also include HTML tags, as well as special tags beginning with @ that are
used to document methods and classes in a standard form. The @ character is followed by a keyword that
defines the purpose of the tag. Table 2-11 shows some of the keywords that you can use:
TABLE 2-11 : HTML Tag Keywords