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 @tag 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 line is a short 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 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)  { ... }

Doclets

A Doclet program works with Javadoc to select which content to include in the documentation, format the presentation of the content and create the file that contains the documentation. A Doclet is written in Java and uses the Doclet API,

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

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

Tags

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

Syntax	Usage	Applies to	Since
@author name	Identifies the author such as "Pat Smith"	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	Version information	Module, Package, Class, Interface, Enum
@since since-text	Describes when this functionality first existed	Class, Interface, Enum, Field, Method
@see reference	Links 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	Marks the method as outdated	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; equivalent to {@literal}	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}	Denotes a default serializable field	Field
{@serialData literal}	Denotes data written by the writeObject( ) or writeExternal( ) methods	Field, Method
{@serialField literal}	Denotes an ObjectStreamField component	Field

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