Java Tools for Development and Testing:
javadoc

What is the javadoc utility and what can it do for you?

Documenting a program, and keeping that documentation up to date, is very important, no matter what programming language you happen to be using. Virtually every programming language provides a way for programmers to comment their code so that they and others can better understand what the code is trying to do. Most software projects have additional "external" documentation as well, some for the developers themselves, and some for the end users of the "released" version of the software. Preparing such documentation and keeping it up to date has always been one of the developer's worst nightmares.

The javadoc utility that comes with the JDK creates separate documentation (in the form of linked HTML pages) from comments placed in Java source code, provided those comments follow certain conventions. A major advantage of this is that so long as the comments in the source code itself are kept current (and why shouldn't they be?), the external documentation can be brought up to date at any time simply by re-running the javadoc utility.

If you are even passably familiar with the documentation provided for the JDK itself, then you will be pleasantly surprised to learn that the documentation produced by javadoc for your own code will have the same appearance and structure as this standard documentation. Thus, knowledgeable users who wish to understand your code will already be familiar with your documentation style.

But don't forget ...

The documentation produced by javadoc is aimed, for the most part, at clients of your code, not at those who might have to maintain or extend it (though it might be useful for them as well). With some additional work it can also be directed at end-users of a complete program. In any case, these documentation comments should not be viewed as a replacement for the usual // and /* ... */ kinds of comments that you should be providing for readers of your source, as always. These two kinds of comments are ignored by javadoc.

When should javadoc comments be prepared?

This is a matter of personal preference, unless you are working in a team environment and the team dictates otherwise. You may find it useful to prepare such comments up front as a form of guidance for yourself. The code does not have to be present for javadoc to do its thing. If you do this, it will be important to modify the comments as required as the development proceeds.

Or, you may write your code and insert only the usual // and /* ... */ kinds of comments as you go, waiting until later, or even till the end, to add the "doc comments".

How do you write javadoc comments? (See also here.)

The special kinds of comments that javadoc recognizes are called, not surprisingly, javadoc comments but you will also see them referred to more generically as documentation comments, or simply as doc comments. Each such comment begins with /** and ends with */, and may contain one or more special tags of the form @tagname, each with its associated information.

As is often the case, the best way to get familiar with javadoc and what it can do is to look at a few typical examples, and those are available elsewhere. On this page, however, we simply provide a brief summary of the main things you need to know, and a number of useful tables.

Typically, the information you will want to provide via doc comments falls into two broad categories:

• General information, such as code author(s), version number(s), modification date(s), and so on, as well as high level descriptions of the purpose and operational characteristics of the software.
• More detailed information about classes and interfaces and their relationships within one or more packages, as well as specific information about the attributes (fields) and operations (methods) of each class.

A typical javadoc comment always appears immediately above the entity it is documenting, and has this general form:

/**
 * A sentence or short paragraph of general description for
 * the class, interface, method or field being documented.
 * The first sentence should be given special attention,
 * since it will be extracted to serve as an even shorter
 * summary of the item.
 *
 * @tag1 description
 * @tag2 description
 */

As illustrated above, each documentation comment must be placed within /** ... */ delimiters. The other leading asterisk (*) characters that appear at the left of each line are optional (starting with javadoc version 1.4), and in any case are removed from the final documentation by javadoc. Nevertheless, they are generally included by convention. Each tag is a special keyword that starts with the @ character and serves as an indicator of some special kind of descriptive information. (See the tables below.)

Sun recommends that tags be included in the following order:

@author       (classes and interfaces only)
@version      (classes and interfaces only)
@param        (methods and constructors only)
@return       (methods only)
@exception    (@throws is a synonym added in Javadoc 1.2)
@see
@since
@serial       (or @serialField or @serialData)
@deprecated

Here are some style guidelines from Sun for writing javadoc comments:

• The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API item. This means the first sentence of each member, class, interface or package description. The javadoc utility copies this first sentence to the appropriate member, class/interface or package summary. This makes it important to write crisp and informative initial sentences that can stand on their own. This first sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag. It is particularly important to write summary sentences that distinguish overloaded methods from one another.
• Write each description to be implementation-independent, but specify any such dependencies where necessary.
• Use HTML <code> tags for keywords and names.
• Omit parentheses for the general form of methods and constructors. Parentheses should only be used if the method or constructor has a non-empty parameter list, and in that case, the parmeter list should be given as well, as a comma-separated list of types.
• It's OK to use phrases instead of complete sentences, in the interests of brevity.
• Use 3rd person (descriptive) rather than 2nd person (prescriptive). For example:

  Gets the label.  (preferred)
  Get the label.   (avoid)
  

• Begin method descriptions with a verb phrase.
• Class/interface/field descriptions can omit the subject and simply state the object. For example:

  A button label.               (preferred)
  The field is a button label.  (avoid)
  

• Use "this" instead of "the" when referring to an object created from the current class. For example:

  Gets the toolkit for this component. (preferred)
  Gets the toolkit for the component.  (avoid)
  

• Add description beyond the API name. That is, make sure your description does not just parrot what the name already conveys.
• Be clear when using the term field, since a "field" may be either a static field (class variable) in a class or another kind of "field" such as a "text field" in the TextField class.
• Avoid the use of Latin terms or abbreviations such as

  "aka" for "also known as"
  "i.e." for "that is" or "to be specific", or
  "viz" for "for example", "in other words" or "namely"
  

Making up your own javadoc tags

The obvious first question here is this: Why would you want to do such a thing? Well, for example, javadoc does not (unlike the doxygen tool, for example) have @pre and @post tags for the pre-conditions post-conditions of a method. So you might well want to "invent" these tags for use in your javadoc comments. The nice thing is that you can do so.

The first thing you need to know, however, is that if you try to use @pre and @post directly, javadoc will tell you that these might be implemented as standard tags sometime in the future and to make sure your code doesn't conflict with some later standard you should use a period in any name that you pick. So ... let's pick @pre.c and @post.c for our tags. The we can use them just like any other tags in the javadoc comments of our methods. But we have to tell javadoc that we are doing this, which we do with the command

javadoc -d html -tag pre.c:mc:"Pre-conditions:" -tag post.c:mc:"Post-conditions:" MyClass.java

• The name of the tag (pre.c)
• Where it can appear (mc for method and constructor documentation)
• The header used in the HTML documentation for this item (Pre-conditions:)

What "source files" does javadoc process?

The javadoc utility will generate output which comes from four different types of "source" files:

1. Class and interface source code files.
2. Package comment files (from a file called package.html in each package directory).
3. Overview comment file. This is an HTML file called whatever you like (but typically overview.html) and containing in its body whatever "overview" documentation you want for a set of packages or a complete application.
4. Miscellaneous unprocessed files, which might include images, sample source code files, applets, and HTML files which are simply too voluminous for inclusion as doc comments in a normal Java source file. These files should be placed in a directory called doc-files, which can be a subdirectory of any package directory containing source files.

How do you run javadoc?

The javadoc program has many options, which may be viewed by entering the command

javadoc -help

and many of which are listed in the table at the end of this section.

Here is a typical use of the utility. Suppose your current directory is your "project directory" in which you have a subdirectory, say src, containing all your *.java source code files that, in turn, contain all your doc comments that you want to turn into viewable documentation in the form of linked HTML files. Suppose this "project directory" also contains an empty subdirectory called docs where you want to store those HTML documentation files. Then you may accomplish your goal by giving this command:

javadoc -d docs src/*java

If src also contains a package called mypackage in a subdirectory called mypackage and you wish to include this package and its doc comments, then use this command:

javadoc -d docs src/*java src/package/*java

Finally (in this very short summary), if you want an "overview" page (i.e., a page that presents an overview discussion of your application, you need to prepare it in a separate ov_file.html and supply its name as a command-line option like this:

javadoc -overview ov_file.html -d docs src/*java src/package/*java

This overview file should be just an "ordinary" HTML file, from which you want the contents between the <body> ... </body> tags to be made available.

What files are produced by javadoc?

The number of files produced by javadoc can be intimidating at first, since even a typical pedagogical example can produce a dozen or more distinct files. For this reason, it is a good idea to place them in their own separate subdirectory, often (as illustrated in the previous section) called docs by convention, but you can call it whatever you like.

The table below shows some of the files that show up when you run javadoc. You don't always want all of these files, and you can suppress many of these files by using the appropriate command-line options when javadoc is run. (See the table at the end of the previous section.)

List of All Topics