javadoc is a program that reads your Java program and constructs HTML documentation for it. It can automatically tell what classes and methods you have, and how they are organized. If you comment your program using special documentation comments ("javadoc comments"), these are integrated into the HTML page.

The advantages of using javadoc are:

• The automatically generated part of the documentation is always up-to-date and in sync with the program.
• The documentation is very professional-looking.
• The documentation is in HTML format (other formats are also available) and is hyperlinked.
• The documentation is in a well-known, well-designed, and standardized format.
• The wide acceptance of javadoc helps dissuade companies from imposing their own (often not very well thought-out) documentation standards.

You can write javadoc comments for: (1) classes, (2) interfaces, (3) methods, (4) constructors, and (5) variables. In each case, the javadoc comment must be placed immediately before the thing that it is commenting. Misplaced javadoc comments will be ignored.

A one-line javadoc comment (such as you might use to describe a variable) looks like this:

/** Total of all funds in all accounts. */
double netWorth;

The more common multi-line comment looks like this:

/**
 * The first sentence of this comment is the summary sentence. The
 * remainder of the sentences will be in the complete description,
 * but not in the summary. If you know HTML, many HTML tags can be
 * used here.
 *
 * You can also use certain "tags" in javadoc comments. Some of the
 * more important tags are:
 * @author Dave Matuszek  (used only for classes and interfaces)
 * @version 1/13/2003  (or a version number; only in classes & interfaces)
 * @param aParameter   Description of a method parameter goes here.
 * @return   Description of return value goes here.
 * @throws Exception   Description of possible Exception goes here.
 */

There are many style rules for the way you should write the English text of the documentation comment; if you want your documentation to look truly professional, you should look into these. The most important rules are:

• Documentation should tell how to use the program, not how it is implemented.
• Don't repeat information that javadoc provides, such as the types of parameters.

Once your program has been commented, you can run javadoc by typing (at the command line):

javadoc -author *.java

This will produce HTML documentation for all the public information in your program. To see all the variables and methods, use

javadoc -author -private *.java