Guidelines for javadoc commenting
Starting with MP2 and for the remainder of the assignments in this
class, you will be required to do your commenting using the javadoc
utility. This program parses through a *.java file, and produces
HTML-style pages which document your code. In order to do this,
you must use some special formatting for your comments. For a general
overview and good instruction on how to use javadoc, see the
Javadoc Home Page.
Specific conventions which must be followed for this class:
- Each routine must have a javadoc-readable header comment. This
means that the header comment must start with /** so javadoc can see
it.
- All subsequent lines in the comment block should start with a *
- The first line of a header comment should be a one-line summary of
the purpose of the routine, and the second line should be blank
except for the required asterisk.
- Authors must be indicated with the @author tag. For this to be
included in the generated html pages, you must use the -author flag
when you are running javadoc. You only need indicate the authors
for the main class, and for any code which you are using from somewhere
else (i.e., code that your team did not write for the assignment.
- Parameters for each method and constructor should be documented using the @param tag.
- Use the @returns tag to indicate return value types for methods.
- You do not need to indicate which exceptions a routine uses unless
they are exception types you have defined, or they are used in a non-standard way.
last modified: 02/01/99