JavaDoc: creating HTML documentation automatically

JavaDoc is a utility that was created by Sun to automatically create HTML documentation for java code. This development tool (with which we will expect you to become familiar) is quite useful, but it also has a few flaws. The biggest advantage to JavaDoc is that it searches through your source code and produces a complete HTML page for you!! However, JavaDoc is a very picky program, and your comments and syntax must be precise, or it won't know what to do.

For your assignments in this course, it will be expected that you include JavaDoc comments in your code, however it is not necessary that you run the javadoc compiler to generate the .html files.

JavaDoc syntax

JavaDoc is used to document the parts of your code that may be used by people that either cannot see your source code, or do not have the time to read through your code and try to figure out what everything does. Therefore, all public identifiers (including classes, interfaces, variables and methods) must be documented. Click here to view the DeliveryRobot class, with JavaDoc comments inserted. If you want to see the page produced from the javadoc command, click here. (These open separate browser windows).

General guidelines

Document all public classes, methods, variables, and interfaces.
All JavaDoc comments begin with /** (instead of /*). Sun recommends that every subsequent line should start with a *, but this is not necessary. If *s are used to start each subsequent line, they should line up with each other (i.e. be in the same vertical column).
Do not begin any other comments in your program with /**, or JavaDoc will try to parse them and have a big problem in doing so.

Class/interface documentation

Begin with /**.
Write a statement explaining what the class does, what it should accomplish, and how to use it. Do not explain individual methods here, they will be explained in separate method comments.
Fill out an @author tag that has simply your name (e.g., @author Ryan Clark )
Fill out a @version tag identifying the version number and/or modification date (e.g., @version 1.1, 2002-05-27)
End with a */.

Method/constructor documentation

Begin with /**.
Write a statement explaining what the method does.
Include a @param statement for every parameter. It should be of the form @param <parameter-name> <description>. Note that you must spell the parameter exactly the same as in your source (but without the object-type in front, javadoc will figure that out). For example, the @param comment for one of the DeliveryRobot constructors is @param numBeepers The number of beepers this robot begins with. Note that there is no puncuation in between the elements of the comment.
Include a @return statement if the method returns a value. It should be of the form @return <description of return value>.

There are other tags such as @exception, @see, @since, and @deprecated, but they are not useful (or necessary) for our purposes.