Javadoc (API documentation)

Overview

Sourcecode documentation is an important but awkward thing to do. Documenting it "offline" typically fails, because developers forget to keep the documentation in sync with changes in the sources. Javadoc provides a solution to this problem:

Javadoc is used to add documentation to Java source code and is also referred to as doc comment. It is directly written into source code by programmers. During the build-cycle with Maven it is automatically parsed. The parsed doc comments are then used to generate documentation in HTML format. This generated sourcecode documentation can be integrated to the program-documentation created with Maven.

Motivation

The description of source code is a very underestimated and thus crucial element for the maintainance and extension of sofware applications. In the majority of cases, it's value is only seen when other developers must get familarized in code such as in Open Source projects with hundreds of community members. In Java, the common method for describing source code is writing doc comments for classes, attributes and methods.

Usage

Doc comments start with /** and are directly placed before classes, attributes and methods:

/**
 * This doc comment should contain a short
 * class description.
 */
public class JavadocExample {

    /** Doc comment for attribute */
    private int attribute;
    
    /**
     * This doc comment should describe the
     * purpose of the constructor
     */
    public JavadocExample() {}
    

    /**
     * This doc comment should describe the
     * purpose of the method
     */    
    public void method() {}
}   
    

From doc comments, it is possible to generate API documentation in HTML format which can be published on the Web. A tool named Javadoc provides this functionality and is delivered with every Java 2 SDK. It can be invoked from the command prompt/terminal with the command javadoc. To see documentation, that is generated by the javadoc tool, go to J2SE 1.5.0 API Documentation.

Every doc comment can contain additonal information as tags (starting with @ or {@). They will be handled in a different way by the javadoc tool.

/**
 * Compares the object ...
 *
 * @param   o the Object to be compared.
 * @return  a negative integer, zero, or a positive integer as this object
 *		is less than, equal to, or greater than the specified object.
 *
 * @throws ClassCastException if the specified object's type prevents it
 *         from being compared to this Object.
 * @author            Daniel Duesentrieb
 */
 public int compareTo(Object o);
 {
     ...
 }

The following table gives a short overview of some tags:

Tag Description
@author Developer name
@deprecated Marks a method or class as deprecated. A warning will be printed during compilation if the method is called.
@exception Description of an exception thrown by the method — see @throws.
@param Description of a method parameter.
@return Description of the return value. Should not be used for methods defined with a void return type.
@see Creates a link to another method or class.
@since jdk-version Since the functionality exists.
@throws Description of an exception thrown by the method. A synonym for @exception introduced in Javadoc 1.2.
@version Version number of a class or method.
{@inheritDoc} Inherits the description of the overwritten method.

Reference

More information can be found in Wikipedia and on the Javadoc Home Page.