Javadoc

From Wikipedia, the free encyclopedia

Javadoc is a documentation generator from Sun Microsystems for generating API documentation in HTML format from Java source code.

The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some IDEs ^[1], such as Netbeans and Eclipse will automatically generate Javadoc HTML. Many file editors will assist the user in producing Javadoc source and will use the Javadoc info as internal references for the programmer.

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

[edit] Structure of a Javadoc comment

A Javadoc comment is set off from code by standard multi-line comment tags /* and */. The opening tag, however, has an extra asterisk, as in /**. The first paragraph is a description of the method documented. Following the description are a varying number of descriptive tags, signifying the parameters of the method (@param), what the method returns (@return), any exceptions the method may throw (@throws), and other less-common tags such as @see (a "see also" tag).

[edit] Example

An example of using Javadoc to document a method follows. Notice that spacing and quantity of characters in this example are as conventions state.

/**
 * Validates a chess move. Use {@link #doMove(int, int, int, int)} to move a piece.
 * 
 * @param theFromFile file from which a piece is being moved
 * @param theFromRank rank from which a piece is being moved
 * @param theToFile   file to which a piece is being moved
 * @param theToRank   rank to which a piece is being moved
 * @return            true if the chess move is valid, otherwise false
 */
boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank)
{
    ... 
}
 
/**
 * Move a chess piece.
 *
 * @see java.math.RoundingMode
 */
boolean doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)
{
    ... 
}

[edit] Criticism

The pages generated by Sun's Javadoc are static HTML pages utilizing frames, rather than using more modern, dynamic techniques. Pages do not include a built-in search function.

[edit] See also

• Comparison of documentation generators

[edit] External links

• Javadoc tool web site
• JavaDoc tags and how to write comments
• JSR 260 Javadoc Tag Technology Update Java Specification Request (defines new Javadoc tags)
• Improve on Javadocs with ashkelon
• A collection of Javadoc doclets
• Javadoc By Examples
• JavadocOnline: Search engine project, to get public Javadocs over Internet
• MyJavadoc: Another search engine project, to get public Javadocs over Internet, with the possibility to submit new Javadocs
• DocJar: Another search engine project, to get public Javadocs over Internet
• Globaldocs: A viewer to browse multiple Javadocs simultaneously.
• Various Java documentations converted to Windows Help format
• Lumentier: A Java search engine project supporting public Javadoc and source code navigation

[edit] Notes