Javadoc

Documentation generator for Java From Wikipedia, the free encyclopedia

Javadoc (also capitalized as JavaDoc or javadoc) is an API documentation generator for the Java programming language. Based on information in Java source code, Javadoc generates documentation formatted as HTML and via extensions, other formats.[1] Javadoc was created by Sun Microsystems and is owned by Oracle today.

The content and formatting of a resulting document are controlled via special markup in source code comments. As this markup is de facto standard and ubiquitous for documenting Java code,[2] many IDEs extract and display the Javadoc information while viewing the source code; often via hover over an associated symbol. Some IDEs, like IntelliJ IDEA, NetBeans and Eclipse, support generating Javadoc template comment blocks.[3] The @tag syntax of Javadoc markup has been re-used by other documentation generators, including Doxygen, JSDoc, EDoc and HeaderDoc.

Javadoc supports extension via doclets and taglets, which allow for generating different output formats and for static analysis of a codebase. For example, JDiff reports changes between two versions of an API.

Although some criticize Javadoc and API document generators in general, one motivation for creating Javadoc was that more traditional (less automated) API documentation is often out-of-date or does not exist due to business constraints such as limited availability of technical writers.[4]

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

Javadoc and the source code comments used by Javadoc, do not affect the performance of a Java executable since comments are ignored by the compiler.

Markup

Summarize
Perspective

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)  { ... }

Markdown

From Java 23 onwards, Javadoc supports the Markdown standard CommonMark on comment lines that start with /// instead of the older multiline format. [6]

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.[7] A Doclet is written in Java and uses the Doclet API,

The StandardDoclet included with Javadoc generates API documentation as frame-based HTML files. Other Doclets are available on the web [citation needed], 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

Summarize
Perspective

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

More information Syntax, Usage ...
Syntax Usage Applies to Since
@author nameIdentifies 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 versionVersion informationModule, Package, Class, Interface, Enum
@since since-textDescribes when this functionality first existedClass, Interface, Enum, Field, Method
@see referenceLinks to other element of documentationClass, Interface, Enum, Field, Method
@param name descriptionDescribes a method parameterMethod
@return descriptionDescribes the return valueMethod
@exception classname description
@throws classname description
Describes an exception that may be thrown from this methodMethod
@deprecated descriptionMarks the method as outdatedClass, Interface, Enum, Field, Method
{@inheritDoc}Copies the description from the overridden methodOverriding Method1.4.0
{@link reference}Link to other symbolClass, 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 fieldStatic Field1.4.0
{@code literal}Formats literal text in the code font; equivalent to {@literal}Class, Interface, Enum, Field, Method1.5.0
{@literal literal}Denotes literal text; the enclosed text is interpreted as not containing HTML markup or nested javadoc tagsClass, Interface, Enum, Field, Method1.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
Close

See also

References

Loading related searches...

Wikiwand - on

Seamless Wikipedia browsing. On steroids.