javadoc is a tool for extracting comments out of Java code, and is part of the JDK installation. It uses some of the technology from the Java compiler to look for special comment tags that you put in your programs. It not only extracts the information marked by these tags, but it also pulls out the class name or method name that adjoins the comment. This way you can get away with the minimal amount of work to generate decent program documentation. The output of javadoc is an HTML file that you can view with your Web browser. javadoc allows you to create and maintain a single source file and automatically generate useful documentation.
javadoc provides a standard for creating documentation, and Sun has provided a reference standard
which you will be expected to adhere to, as Java programmers.You can find additional references for javadoc at
A javadoc comment is written in HTML and must precede a
public class, field, constructor
or method declaration.
It is made up of two parts -- a description followed by block tags.
All of the javadoc commands occur only within /**
comments. The comments end with */ as usual.
For example,
/** A class comment with block tag
@author Kenneth Harris */
public class Doc {
/** A variable comment */
public int v;
/** A constructor comment with block tag
@param v value assigned */
public Doc(int v) { this.v=v; }
/** A method comment */
public void foo() {};
}
The output for the preceding code is an HTML file that
has the same standard format as all the rest of the Java documentation.
Warning: you may not put anything between the javadoc comment and the class, variable or method.
Javadoc passes HTML commands through to the generated HTML document. You can use HTML just as you would any other Web document to format your descriptions. For example,
/** some great sluggers in the <code>Slugger</code> class: * <ol> * <li> Hank Aaron, <code> AARON </code> * >li> Babe Ruth, <code> RUTH </code> * >li> Willie Mays, <code> MAYS </code> * </ol> */Keywords and names should be offset by <code> </code> (see javadoc style.) Also, note that javadoc ignores the lead asterisk '*' on each line.
You must include a
@param name description
@return description
@exception name description@param tag for every parameter in
a public method and every public constructor. You must include a
@return tag for any method that has a
non-void return
(no tag for constructors.) You must include
@exception tags for every Exception your
method throws. (You may also use the synonym @throws.)
Here are some of the javadoc tags available for code documentation.
They should be included in the order (when appropriate
@param
@return
@exception
where name is the identifier name in the parameter list and
description is text that continues until the next tag. See
parameter style for suggestions of what to write.
There should be one @param tag for every parameter, and
the tags should occur in the same order as the parameters in the
method.
This tag is only valid in a method with a return value, and should
describe the return type and permissible range of values.
Follow the same style guidlines as for the parameter tag.
@throws name description
These are synonyms, which cause javadoc to
add a "Throws" subheading to the generated documentation, with
the name and description to appear.