The Java language has special comments called "javadoc comments" that can be used to automatically generate on-line documentation for your classes. The tool we use to create the documentation is called javadoc (hence the name of the comments). Each javadoc comment is associated with an element of your program (a class or a method), and its purpose is to describe that element. You can see examples of on-line documentation generated using javadoc on the Sun Java documentation site -- such as this page for the class String.
Javadoc comments start with a slash and two stars -- /** -- and continue until a star and slash -- */. Everything inside those delimiters is part of the javadoc comment. A javadoc comment can be a single line, like this:
/** This is a single line javadoc comment */but is usually written over several lines, with a space and a star at the beginning of each line "in the middle" -- like this:
/** * A javadoc comment * that goes over * multiple lines */
Every javadoc comment begins with a description of the program element. This description can be a single line of plain text, or several lines of HTML code. When the javadoc program is run, it includes that description in the Web page(s) documenting that element.
A javadoc comment can include tags --
parts of the comment that the javadoc program understands
and treats specially.
These tags allow the programmer to specify such things as
the author of the element
(the @author tag)
and the version of the element
(the @version tag).
The javadoc program reads these tags
(and the information that goes with them)
and adds that information to the Web pages it generates.
The tag must appear exactly as shown
(an @ sign followed by the name of the tag),
and it must be a tag that javadoc knows about
(you can actually teach it about new tags,
but that's beyond what I need you to know).
The only tags you need to know about
are the ones shown below.
Classes
Every class file you hand in must contain javadoc comments. These comments appear just before the class definition (and after any import commands). The format of the javadoc for the class is
/** * [FILE DESCRIPTION GOES HERE] * * @author [YOUR STUDENT NUMBER AND NAME GO HERE] */The bits in [brackets] need to be changed. (The [brackets] themselves should not appear in the result.) Each of the parts (description and author) must be provided with each file.
For example, a converter class:
/** * A collection of methods for converting from imperial/US measures to metric/SI * measures (and <em>vice versa</em>). * * @author Mark Young (A00000000) */
These comments appear just before the method definition. The format of the javadoc for a method is
/** * [METHOD DESCRIPTION GOES HERE] * * @param [PARAM NAME] [PARAM DESCRIPTION] * @return [RETURN VALUE DESCRIPTION] * @throws [EXCEPTION NAME] [WHEN THIS EXCEPTION GETS THROWN] */Some of the parts are optional (see below). The bits in [brackets] need to be changed. (The [brackets] themselves should not appear in the result.)
The function description is required. It gives a description of what the method does. The description's length should be proportional to its complexity. For a getter a single line is generally sufficient. For a setter, two or three sentences may be required (including a discussion of what happens if the argument is inappropriate). More complicated methods should have a full description, elaborating on all the various actions the method might take.
The param will appear only if the method has parameters. If the method does have parameters, then there will be one param comment per parameter. Every one of the parameters must be named and described. Of course the parameter name itself should be descriptive, but the longer description will provide more details, including any pre- or post-conditions.
The return will appear only if the method is value-returning. (That is, void methods will not have a return part.)
The throws will appear
only if the method is designed to throw that exception.
That is,
if the design of the method specifies
that it should throw that exception
under the circumstances described.
Normally the throw command
will be in this method.
(It is possible that it will be in a method
that this one calls in order to check for the condition --
such as a method that checks whether an argument is negative
and throws an IllegalArgumentException if it is.)
For example, a method to convert from feet and inches to centimetres:
/** * Convert a distance in feet and inches to centimetres. No error checking on * the parameters: garbage in; garbage out! * * @param feet the number of feet * @param inches the number of inches * @return the cm equivalent of the distance in feet and inches */
Another example, a method for printing a wrapped paragraph:
/** * Print a paragraph on System.out. No line is longer than the line width and * there is a blank line afterwards. For output to be correct, it's necessary * that the text contains no "word" longer than the current line width, and also * that System.out started at the beginning of a line. * <p> * After the given text has been printed, System.out is at the beginning of a * line after one blank line. * * @param text the text to be printed on the screen */