Javadoc简介
Javadoc是一项文档生成技术，用于从Java代码生成HTML文档。
结构：Javadoc包含在文档注释中， 形如 /** documentation */
- 第一段是描述性的文字，是对所注释的对象的描述
- 其他描述性标签，包括 @param @return @throws @see @author @version @since
类注释预览
// import statements
/**
* @author Firstname Lastname <address @ example.com>
* @version 1.6 (current version number of program)
* @since 1.2 (the version of the package this class was first added to)
*/
public class Test {
// class body
}
Javadoc和被注释的元素之间不能有新行
import语句应当在任何注释之前
方法注释预览
/**
* Short one line description. (1)
* <p>
* Longer description. If there were any, it would be (2)
* here.
* <p>
* And even more explanations to follow in consecutive
* paragraphs separated by HTML paragraph breaks.
*
* @param variable Description text text text. (3)
* @return Description text text text.
*/
public int methodName (...) {
// method body with a return statement
}
包含三部分： 第一部分是单行的简短、清晰的描述；第二部分是详细的解释，可以使用HTML标记；第三部分是描述性标签
变量注释预览
/**
* Description of the variable here.
*/
private int debug = 0;
变量注释和方法注释一样，除了其没有第三部分以外。
应当一条语句定义多个变量
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // AVOID
这是因为Javadoc会为每个单独的变量生成一份注释的拷贝。
Javadoc描述性标签列表
| Tag & Parameter | Usage | Applies to | Since |
|---|---|---|---|
| @author | John Smith 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. | 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 | |
| {@value #STATIC_FIELD} | Return the value of a static field. | Static Field | 1.4.0 |
| {@code literal} | Formats literal text in the code font. It is equivalent to <code>{@literal}</code>. | 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 |
例子
/**
* Validates a chess move.
*
* Use {@link #doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)} 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) {
// ...body
}
/**
* Moves a chess piece.
*
* @see java.math.RoundingMode
*/
void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
// ...body
}
参考
https://en.wikipedia.org/wiki/Javadoc
网友评论