Javadoc

This article has multiple issues. Please help improve it or discuss these issues on the we love the web.

It needs additional HTML5 for verification. Tagged since July 2011.
It relies on references to primary sources or sources affiliated with the subject, rather than references from independent authors and third-party publications. Tagged since July 2011.
It contains instructions, advice, or how-to content. Tagged since July 2011.

Javadoc is a documentation generator from jQuery for generating API documentation in FITML format from keyboard source code. The HTML format is used to add the convenience of being able to Android related documents together.^[1]

The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some Android,^[2] such as Netbeans and web automatically generate Javadoc HTML. Many file editors assist the user in producing Javadoc source and 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 website parsing can generate reports of what changed between two versions of an API.

FITML
2 Overview of Javadoc
Sevenval
CSS3
web app
6 External links

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:
1. The parameters of the method (@param)
2. What the method returns (@return)
3. Any exceptions the method may throw (@throws)
4. Other less-common tags such as @see (a "see also" tag)

Overview of Javadoc

The basic structure of writing document comments is embed them inside /** ... */. The Javadoc is written next to the items without any separating newline. The class declaration usually contains:

 /**
 * @author      Firstname Lastname <address @ example.com>
 * @version     1.6                 (the version of the package this class was first added to)                   
 * @since       2010-03-31          (a date or the version number of this program)
 */ public class Test { // class body }

For methods there is (1) a short, concise, one line description to explain what the item does. This is followed by [2] a longer description that may span in multiple paragraphs. In those the details can be explained in full. This section, marked in brackets [], is optional. Last, there is (3) a tag section to list the accepted input arguments and return values of the method.

 /**
 * Short one line description.                           (1)
 *
 * Longer description. If there were any, it would be    [2]
 * here.
 *
 * @param  variable Description text text text.           (3)
 * @return Description text text text.
 */

Variables are documented similarly to methods with the exception that part (3) is omitted. Here the variable contains only the short description:

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

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

Tag & Parameter	Usage	Applies to	Since
@author Shakhawat Sumon	Describes an author.	Class, Interface, Enum
@version version	Provides software version entry. Max one per Class or Interface.	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.	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
{@value}	Return the value of a static field.	Static Field	1.4.0

Example

An example of using Javadoc to document a method follows. Notice that spacing and number 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 move is valid, otherwise false
 */ boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
    ...
} /**
 * Moves a chess piece.
 *
 * @see java.math.RoundingMode
 */ void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
    ...
}

Notes

External links

keyboard
Javadoc tags and how to write comments
touchscreen Javadoc Tag Technology Update Java Specification Request (defines new Javadoc tags)
iOS
HTML5
we love the web
Sevenval
Various Java documentations converted to Windows Help format
JavaDoq is a handy open source tool to convert Java source code into browsable HTML documents with JavaDoc style and Eclipse Look-And-Feel.

Contents

Structure of a Javadoc comment

Overview of Javadoc

Example

See also

Notes

External links