javadoc Documentation Tool

javadoc, the Java documentation creator, takes a .java source code file or package name as input and generates detailed documentation in HTML format. For javadoc to create full documentation for a program, a special type of comment statement must be used in the program's source code. Tutorial programs in this tutorial use //, /*, and */ in source code to create comments—information for people who are trying to make sense of the program. Java also has a more structured type of comment that can be read by the javadoc tool. This comment is used to describe program elements such as classes, variables, objects, and methods. It takes the following format:

/** A descriptive sentence or paragraph.
 * @tag1 Description of this tag.
 * @tag2 Description of this tag.

A Java documentation comment should be placed immediately above the program element it is documenting and should succinctly explain what the program element is. For example, if the comment precedes a class statement, it will describe the purpose of the class. In addition to the descriptive text, different items can be used to document the program element further. These items, called tags, are preceded by an @ sign and are followed by a space and a descriptive sentence or paragraph. Listing B.3 contains a thoroughly documented version of the AppInfo applet called AppInfo2. The following tags are used in this program:

  • @author— The program's author. This tag can be used only when documenting a class, and it will be ignored unless the –author option is used when javadoc is run.
  • @version text— The program's version number. This also is restricted to class documentation, and it requires the –version option when you're running javadoc or the tag will be ignored.
  • @return text— The variable or object returned by the method being documented.
  • @serial text— A description of the data type and possible values for a variable or object that can be serialized, saved to disk along with the values of its variables and retrieved later.
Listing B.3. The Full Text of
 1: import java.awt.*;
 3: /** This class displays the values of three parameters:
 4: * Name, Date and Version.
 5: * @author <a href="">Rogers Cadenhead</a>
 6: * @version 4.0
 7: */
 8: public class AppInfo2 extends javax.swing.JApplet {
 9: /**
10: * @serial The programmer's name.
11: */
12: String name;
13: /**
14: * @serial The current date.
15: */
16: String date;
17: /**
18: * @serial The program's version number.
19: */
20: int version;
21: 22: /**
23: * This method describes the applet for any browsing tool that
24: * requests information from the program.
25: * @return A String describing the applet.
26: */
27: public String getAppletInfo() {
28: String response = "This applet demonstrates the "
29: + "use of the Applet's Info feature.";
30: return response;
31: }
32: 33: /**
34: * This method describes the parameters that the applet can take
35: * for any browsing tool that requests this information.
36: * @return An array of String[] objects for each parameter.
37: */
38: public String[][] getParameterInfo() {
39: String[] p1 = { "Name", "String", "Programmer's name" };
40: String[] p2 = { "Date", "String", "Today's date" };
41: String[] p3 = { "Version", "int", "Version number" };
42: String[][] response = { p1, p2, p3 };
43: return response;
44: }
46: /**
47: * This method is called when the applet is first initialized.
48: */
49: public void init() {
50: name = getParameter("Name");
51: date = getParameter("Date");
52: String versText = getParameter("Version");
53: if (versText != null) {
54: version = Integer.parseInt(versText);
55: }
56: }
57: 58: /**
59: * This method is called when the applet's display window is
60: * being repainted.
61: */
62: public void paint(Graphics screen) {
63: Graphics2D screen2D = (Graphics2D)screen;
64: screen.drawString("Name: " + name, 5, 50);
65: screen.drawString("Date: " + date, 5, 100);
66: screen.drawString("Version: " + version, 5, 150);
67: }

The following command will create HTML documentation from the source code file

javadoc -author -version

The Java documentation tool will create several different web pages in the same folder as These pages will document the program in the same manner as Sun's official documentation for the Java 2 class library.

Did you Know?

To see the official documentation for Java 2 JDK 1.5 and the Java class libraries, visit

To see the documentation that javadoc has created for AppInfo2, load the newly created web page index.html on your web browser. Screenshot B.4 shows this page loaded with Mozilla Firefox.

Screenshot B.4. Java documentation for the AppInfo2 program.

[View full size image]Java ScreenShot

The javadoc tool produces extensively hyperlinked web pages. Navigate through the pages to see where the information in your documentation comments and tags shows up. If you're familiar with HTML markup, you can use HTML tags such as A, TT, and B within your documentation comments. Line 5 of the AppInfo2 program uses an A tag to turn the text "Rogers Cadenhead" into a hyperlink to this tutorial's website. The javadoc tool also can be used to document an entire package by specifying the package name as a command-line argument. HTML files will be created for each .java file in the package, along with an HTML file indexing the package. If you would like the Java documentation to be produced in a different folder than the default, use the -d option followed by a space and the folder name. The following command creates Java documentation for AppInfo2 in a folder called C:\JavaDocs\:

javadoc -author -version -d C:\JavaDocs\

The following list details the other tags you can use in Java documentation comments:

  • @deprecated text— A note that this class, method, object, or variable has been deprecated. This causes the javac compiler to issue a deprecation warning when the feature is used in a program that's being compiled.
  • @exception class description— Used with methods that throw exceptions, this tag documents the exception's class name and its description.
  • @param name description— Used with methods, this tag documents the name of an argument and a description of the values the argument can hold.
  • @see class— This tag indicates the name of another class, which will be turned into a hyperlink to the Java documentation of that class. This can be used without restriction in comments.
  • @see class#method— This tag indicates the name of a method of another class, which will be used for a hyperlink directly to the documentation of that method. This is usable without restriction.
  • @since text— This tag indicates a note describing when a method or feature was added to its class library.