javadoc is very easy to use, and produces great-looking documentation.

If you use the Java 1.1 version, you get HTML pages without frames, but they require you to include a few .gif files to look their best. If you use the Java 1.2 (same as Java 2) version, you get HTML pages with frames, and they don't require you to download and install .gif files. To see what these look like, you can look at the Java 1.1 API docs and the Java 2 API docs, each produced with the corresponding version of javadoc.

It doesn't matter what version of Java your program uses, you can use either version of javadoc with it. On the whole I think it's easier to use javadoc 1.2 (downloading the .gif files is a nuisance), but if you want to use 1.1, this is copied from the javadoc FAQ (http://java.sun.com/products/jdk/javadoc/faq.html):

C1.   Where can I get the .gif images that Javadoc 1.1.x output uses?

Download the .gif images and "API users guide" file here (~24K). This latter file is named API_users_guide.html, which you access by clicking on the link "API User's Guide" in the upper left corner of the first page (packages.html). Please see the README. You can also obtain them from the docs/api/images/ directory in the downloadable JDK docs.

To run javadoc, use:  javadoc -package -author *.java

javadoc comments begin with /** and end with */. Within the comment, spaces and asterisks at the beginning of a line are ignored. In addition, simple HTML commands within the comment are recognized and treated properly. Thus, a javadoc comment might look like:

/**
 * This class implements the <b>Magic Forest</b> assignment.
 * @author John Q. Student
 */

A javadoc comment applies to the immediately following

• class
• interface
• method
• field (variable declaration)

A javadoc comment not immediately followed by the definition of a class, interface, method, or field will be ignored. Also, if you use the above command line, only information that is public or package will appear in the output; anything having to do with protected or private definitions will be ignored. If your javadoc output doesn't contain something you think should be there, that's probably why.

That's all you need to know about javadoc for this course. If you want to know more, Sun's documentation is at http://java.sun.com/products/jdk/1.1/docs/tooldocs/win32/javadoc.html. Also, if you decide to become a serious Java programmer, you should learn correct javadoc style (not required for this course); see the style guide at http://java.sun.com/products/jdk/javadoc/writingdoccomments/index.html.