Javadoc
From Wikipedia, the free encyclopedia.
Javadoc is a computer software tool from Sun Microsystems for generating API documentation into HTML format from Java source code.
Javadoc is the industry standard for documenting Java classes. Most IDEs will automatically generate Javadoc HTML.
Developers use certain commenting styles and Javadoc tags when documenting source code. A Java block comment starting with /** will begin a Javadoc comment block which will be included in the generated HTML. A Javadoc tag begins with an "@" (at sign). Some tags are provided in the following table.
tag | description |
---|---|
@author | Developer name |
@deprecated | Marks a method as deprecated. Some IDEs will issue a compilation warning if the method is called. |
@exception | Documents an exception thrown by a method — also see @throws. |
@param | Defines a method parameter. Required for each parameter. |
@return | Documents the return value. This tag should not be used for constructors or methods defined with a void return type. |
@returns | A synonym for @return. |
@see | Documents an association to another method or class. |
@since | Documents when a method was added to a class. |
@throws | Documents an exception thrown by a method. A synonym for @exception introduced in Javadoc 1.2. |
@version | Provides the version number of a class or method. |
An example for a method follows.
/** * Validates a chess move. * @author John Doe * @param theFromFile File of piece being moved * @param theFromRank Rank of piece being moved * @param theToFile File of destination square * @param theToRank Rank of destination square * @return true if a valid chess move or false if invalid */ boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) { ... }
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.