They begin with /**

They end with */

Every line between the /** and */ begins with an asterisk (*)

They may contain "tags" which begin with the @ symbol (@author, @version, @param, etc.)

The first sentence of a javadoc comment must be a statement which concisely describes the item. The first sentence MUST end with a period.

All other sentences in a javadoc comment are descriptive, and are meant to expound upon the item.

They are directly above the item that they describe. There are NO blank lines between the javadoc comment and the item they are describing.

2. What do I have to "javadoc" in my programs?

In your programs, you must javadoc:

The class itself (this is your ident box)

All instance variables

All static variables

All methods

You do NOT javadoc:

Closing braces (they must be commented, but not with a javadoc comment)

Local variables

3. What is the "javadoc" tool?

The javadoc tool is a program that can be run to produce HTML files from your code. It produces its output based on your javadoc comments.

4. Why isn't the author information included in the resulting HTML file?

By default, the javadoc tool does not include the author information. To include that information, run javadoc with the "-author" option. If the author information still does not appear, check to make sure that the @author tag is NOT followed by a colon (i.e.,"@author:"). (Unfortunately, the colon pops up a lot - you'll see it in ident boxes every now and then)

5. Why does javadoc omit the version information? It isn't in the resulting HTML file!

By default, the javadoc tool does not include the version information. To include that information, run javadoc with the "-version" option.

6. Why aren't private methods being shown in the resulting HTML file?

By default, the javadoc tool does not include private methods. To include them, run javadoc with the "-private" option.

7. How can I check if I have made my javadoc comments correctly?

Use the javadoc tool with the "-author", "-version" and "-private" option. For example:

javadoc -author -version -private *.java

This will create HTML files with all of the things that SHOULD have javadoc comments. Load the HTML files that correspond with the classes that you made in order to see if everything "looks" correct.