Java Fundamentals Tutorial: Javadoc

Prev   Next

8. JavaDoc

Documenting Java Code

8.1. What is JavaDoc?

  • Doc comments (also known informally as Javadoc comments, although this technically violates trademark usage) document your APIs for other programmers who use your classes and for maintenance programmers.
  • Doc comments standardize the way source code is documented.
  • Documentation is kept in the source file, so it’s easier for developers to keep it in sync with the code.
  • You can document packages, classes, constructors, fields, and methods.

Doc comments are a very important feature of Java, because it defines a common way for developers to communicate about their code.

It makes using third-party classes (including the Java Library itself) much easier because everything is documented the same way.

8.2. Reading Doc Comments (Java API)

Figure 5. JavaDoc Page For Java 1.5

JavaDoc Page For Java 1.5

You can browse the Java API documentation online at: http://download.oracle.com/javase/6/docs/api/ Alternatively, you can download the documentation from http://www.oracle.com/technetwork/java/javase/downloads//bookshelf/java_fundamentals_tutorial/index and browse it locally.

  • The top-left frame defines all available packages.
  • Clicking on a package name in the top-left frame causes the bottom-left frame to display all interfaces, classes, enumerations, exceptions, errors, and annotations in that package.
  • Clicking on the package name in the bottom-left frame (at top) causes the right-hand frame to display the information for that package.
  • Clicking on an interface, class, enumeration, exception, error, or annotation in the bottom-left frame, causes the right-hand frame to display the information about that entity. Links within the right-hand frame usually jump to anchors within the same page.

8.3. Defining JavaDoc

  • Use /** */ comments right before the entities that are to be documented.

    • You can have whitespace between the doc comment and the declaration, but no other code. For example, don’t put import statements between your doc comment and a class declaration.
    • If a doc comment line begins with a * preceded by optional whitespace, those characters are ignored.
    • As of Java 1.4, leading whitespace is preserved if a line does not begin with a * character. This allows you to include formatted code fragments (wrapped with HTML <pre> tags) in your documentation.
  • A doc comment consists of an optional main description followed by an optional tag section.
  • A doc comment can contain HTML markup, but keep it simple (as in, keep it <em>simple</em>).
  • The first sentence of the main description (ending in a period followed by a space, tab, line terminator, or first block tag) is used as the summary description for the declared entity.

8.4. Doc Comment Tags

  • Block tags have the format @tag description. There are many block tags available, but the more commonly used ones are:

    @author name
    Author Name (class/interface only)
    @version major.minor.patch
    Version number (class/interface only)
    @param name description
    Description of parameter (method only)
    @return description
    Description (method only)
    @throws Throwable description
    Description of exception (exceptions are discussed in the next module)
    @deprecated explanation
    Explanation (method only)
    @see package.class#member label
    A hyperlink to a reference package/class/member or field. Or simple text for a “See Also” reference

  • Java also supports various inline tags of the form {@tag text_content} to handle special text inline. The most important ones are:

    {@literal text}
    Treat the text as literal, suppressing the processing of HTML markup and nested doc comment tags
    {@code text}
    Treat the text as literal, suppressing the processing of HTML markup and nested doc comment tags, and render the text in a code font

Use doc comments! At least document everything that is marked public or protected.

This is an example of how you could document an interface:

/**
 * Simple calculator operation.
 * @author <a href="mailto:me@my.com">Me</a>
 * @version 1.0
 */
public interface Operation {
    /**
     * Perform a single calculation.
     * @param operand the operand to use for calculation.
     */
    public void calculate(double operand);

    /**
     * Get the current result.
     * @return the current result. If no calculations were
     *         performed the result is undefined.
     */
    public double getResult();
}

For the full doc comments HOWTO (including a complete list of doc comment tags), please see: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

8.5. Generating Doc Comment Output

  • To generate HTML formatted documentation, run the javadoc command-line tool on your source files to generate the HTML API files (including indexes): 
javadoc -d /path/to/output /path/to/*.java

  • You can also specify one or more package names as arguments, in which case javadoc generates output for all classes and interfaces in those packages.

    • Open the generated /path/to/output//bookshelf/java_fundamentals_tutorial/index file in your browser.

Figure 6. Doc Comment Generation Example

Doc Comment Generation Example

Prev   Next
 Home | ToC