Main Page

Previous Next

Program Comments

We have been adding comments in all our examples so far, so you already know that // plus 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 comment out lines of code. If you want to remove some code from a program temporarily, you just need to add // at the beginning of each line you want to eliminate.

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 next */ will be 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.      *
 ***************************************/

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. All the documentation that you get with the JDK is produced in this way. A program called javadoc, which contains the documentation comments, produces the documentation once it is processed.

The documentation that is generated is in the form of HTML web pages that can be viewed using a browser such as Netscape Navigator or Internet Explorer. A full discussion of documentation comments is outside the scope of this book – not because they are difficult, they aren't, but it would need a lot of pages to cover them properly. We will 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:

/**
 * 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 *.

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 @ is followed by a keyword that defines the purpose of the tag. Here are some of the keywords that you can use:

@author

Used to define the author of the code.

@deprecated

Used in the documentation of library classes and methods to indicate that they have been superseded and generally should not be used in new applications.

@exception

Used to document exceptions that the code can throw and the circumstance which can cause this to occur.

{@link}

Generates a link to another part of the documentation within the documentation that is produced. The curly brackets are used to separate it from the rest of the in-line text.

@param

Used to describe the parameters for a method.

@return

Used to document the value returned from a method.

@see

Used to specify cross references to some other part of the code such as another class or a method. It can also reference a URL.

@throws

A synonym for @exception.

@version

Used to describe the current version of the code.

You can use any HTML tags within a documentation comment except for header tags. The HTML tags you insert are used to structure and format the documentation appropriately when it is viewed, and javadoc will add HTML tags to format the comments that include the special @ tags that we mentioned above.

The few comments I have made here really don't do justice to the power and scope of javadoc. For that you need to look into it in detail. The JDK comes with the javadoc program and documentation. Javadoc also has its own home page on the Javasoft web site at http://java.sun.com/products/jdk/javadoc/.

Previous Next
JavaScript Editor Java Tutorials Free JavaScript Editor