Javadoc

Javadoc is a documentation generator for the Java programming language. It generates API documentation in HTML format from source code. It was created by Sun Microsystems and is owned by Oracle today.

The Javadoc comment format is the de facto standard for documenting Java classes. Some IDEs, like IntelliJ IDEA, NetBeans and Eclipse, automatically generate Javadoc templates. Many file editors assist the user in producing Javadoc source and show the Javadoc info (via hover over an associated symbol for example) to assist with programming.

Javadoc also provides an API for creating doclets and taglets, which allows users to analyze the structure of a Java application. This is how JDiff can generate reports of what changed between two versions of an API.

Javadoc does not affect the performance of a Java executable since comments are ignored by the compiler.

History

Javadoc has been part of Java since its first release, and is often updated with each release of the Java Development Kit.

Prior to the use of documentation generators, technical writers would often write API documentation that would mismatch the actual source code.

The @field syntax of Javadoc has been re-used by other documentation generators, including Doxygen, JSDoc, EDoc and HeaderDoc.

Design

Javadoc ignores comments unless they are specially marked. A Javadoc comment is marked with an extra asterisk after the start of a multi-line comment: /**. A comment block pertains to the symbol that follows the block.

An example of a class header block follows:

/**
 * Provides some service
 * @author      Jill Smith <address @ example.com>
 * @version     1.6
 * @since       1.2
 */
public class Test {}

For a method, the first paragraph is a description of the method. If more detail is warranted, then it may be followed by a longer description in additional paragraphs. Following that are optionally various fields such as:

• @param to describe a method parameter
• @return to describe the return value
• @throws to describe exceptions the method may throw
• @see and other less-common tags

Various aspects of HTML as supported via Javadoc. For example <p> denotes a paragraph break.

An example of a method header block follows:

/**
 * One-line description
 * <p>
 * Longer description. If there were any, it would be here.
 * <p>
 * And even more explanation to follow in consecutive
 * paragraphs separated by paragraph break.
 *
 * @param variableName Description...
 * @return Description...
 */
public int methodName(...) { ... }

Variables can also be documented. For example:

/**
 * Description of the variable here
 */
private int debug = 0;

A more complete example follows:

/**
 * Validates a chess move
 *
 * <p>Use {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} to move a piece.
 *
 * @param fromFile file from which a piece is being moved
 * @param fromRank rank from which a piece is being moved
 * @param toFile file to which a piece is being moved
 * @param toRank rank to which a piece is being moved
 * @return true if the move is valid, otherwise false
 * @since 1.0
 */
boolean isValidMove(int fromFile, int fromRank, int toFile, int toRank) { ... }

/**
 * Moves a chess piece
 *
 * @see java.math.RoundingMode
 */
void doMove(int fromFile, int fromRank, int toFile, int toRank)  { ... }

Table of Javadoc tags

Some of the available Javadoc tags are listed in the table below:

Tag & Parameter	Usage	Applies to	Since
@author John Smith	Describes an author.	Class, Interface, Enum
{@docRoot}	Represents the relative path to the generated document's root directory from any generated page.	Class, Interface, Enum, Field, Method
@version version	Provides software version information.	Module, Package, Class, Interface, Enum
@since since-text	Describes when this functionality has first existed.	Class, Interface, Enum, Field, Method
@see reference	Provides a link to other element of documentation.	Class, Interface, Enum, Field, Method
@param name description	Describes a method parameter.	Method
@return description	Describes the return value.	Method
@exception classname description @throws classname description	Describes an exception that may be thrown from this method.	Method
@deprecated description	Describes an outdated method.	Class, Interface, Enum, Field, Method
{@inheritDoc}	Copies the description from the overridden method.	Overriding Method	1.4.0
{@link reference}	Link to other symbol.	Class, Interface, Enum, Field, Method
{@linkplain reference}	Identical to {@link}, except the link's label is displayed in plain text than code font.	Class, Interface, Enum, Field, Method
{@value #STATIC_FIELD}	Return the value of a static field.	Static Field	1.4.0
{@code literal}	Formats literal text in the code font. It is equivalent to <code>{@literal}</code>.	Class, Interface, Enum, Field, Method	1.5.0
{@literal literal}	Denotes literal text. The enclosed text is interpreted as not containing HTML markup or nested javadoc tags.	Class, Interface, Enum, Field, Method	1.5.0
{@serial literal}	Used in the doc comment for a default serializable field.	Field
{@serialData literal}	Documents the data written by the writeObject( ) or writeExternal( ) methods.	Field, Method
{@serialField literal}	Documents an ObjectStreamField component.	Field

Doclets

Doclet programs work with the Javadoc tool to generate documentation from code written in Java.

Doclets are written in the Java programming language and use the Doclet API to:

• Select which content to include in the documentation
• Format the presentation of the content
• Create the file that contains the documentation

The StandardDoclet[1] included with Javadoc generates API documentation as frame-based HTML files. Many non-standard doclets are available on the web , often for free. These can be used to:

• Create other non-API types of documentation
• Output the documentation to other non-HTML file types such as PDF
• Output the documentation as HTML with additional features such as a search or with embedded UML diagrams generated from the Java classes

See also

• Comparison of documentation generators
• .NET XML documentation comments

External links

• Java Platform, Standard Edition Javadoc Guide
• JSR 260 Javadoc Tag Technology Update Java Specification Request (defines new Javadoc tags)
• Improve on Javadoc with ashkelon
• Various Java documentations converted to Windows Help format