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
/** * [CLASS 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 methods will not require every tag (see below). The bits in [brackets] need to be changed. (The [brackets] themselves should not appear in the result.)
Every method requires a method description. 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 description of which values are appropriate, and what action (other than throwing an exception) is taken for inappropriate values). 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 tag 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.
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.)
There is one more javadoc tag that you should use. The @code tag can be used inside the descriptions to format a word in a fixed-width font. The tag is preceeded by an open brace and the closing brace follows the part of the text that should be formatted. For example, {@code inches} formats the word "inches" as inches.
You won't see any difference in NetBeans because the document produced is entirely in a fixed-width font. But it makes a difference when viewed in an external browser.
/** * Convert a distance in feet and inches to centimetres. The numbers must not * be negative, and {@code inches} must be less than 12. * * @param feet the number of feet * @param inches the number of inches * @return the cm equivalent of the distance in feet and inches * @throws IllegalArgumentException if {@code feet} is negative, or if * {@code inches} is outside the range [0, 12) */
A method for printing a wrapped paragraph:
/** * Print a paragraph on System.out. No line is longer than {@code MAX_WIDTH} and * there is a blank line afterwards. After the given text has been printed, * System.out is at the beginning of a line after one blank line. Lines are * broken at whitespace. The method will not hyphenate words or even break the * line at a hyphen unless it is followed by whitespace. * <p> * <b>NOTE:</b> The line will overflow if there is a "word" that's longer than * the line length. <B>Also,</B> the line may overflow if System.out is not * at the start of a line when this method is called. * * @param text the text to be printed on the screen */