Javadoc(最初是JavaDoc)[1]是由Sun Microsystems為Java語言(現在由甲骨文公司擁有)創建的文檔生成器,用於從Java原始碼生成HTML格式的API文檔,HTML格式用於增加將相關文檔連結在一起的便利性。[2]
![Thumb](http://upload.wikimedia.org/wikipedia/commons/thumb/c/cb/Javadoc_screenshot.png/640px-Javadoc_screenshot.png)
Javadoc使用的「doc comments」格式[3] 是記錄Java類的事實上的行業標準。一些IDE,[4]如IntelliJ IDEA、NetBeans和Eclipse,可以自動生成Javadoc HTML。許多文件編輯器幫助用戶生成Javadoc原始碼並使用Javadoc信息作為程式設計師的內部引用。
Javadoc還提供了用於創建doclet和taglet的API,允許用戶分析Java應用程式的結構,這就是JDiff如何生成兩個API版本之間發生變化的報告。
Javadoc不影響Java中的性能,因為在編譯時會刪除所有註釋。編寫註釋和Javadoc是為了更好地理解代碼,從而更好地維護代碼。
Javadoc是早期的Java語言文檔生成器。[5]在使用文檔生成器之前,習慣上由專業的技術編寫者編輯文檔,他們通常只編寫軟件的獨立文檔,[6]但要使這些文檔與軟件本身保持同步要困難得多。
自第一個版本以來,Java一直使用Javadoc,並且通常在Java開發工具包的每個新版本上都會更新。
通過標準多行註釋標記/*
and */
從代碼中引發Javadoc註釋。起始標記(稱為開始 - 註釋分隔符)具有額外的星號,如/**
中所示。
- 第一段是對所記錄方法的描述。
- 在描述之後是不同數量的描述性標籤,表示:
- 方法的參數(
@param
) - 方法返回的內容(
@return
) - 方法可能拋出的任何異常(
@exception
) - 其他不太常見的標籤,如
@see
(「另見」標籤)
- 方法的參數(
編寫文檔註釋的基本結構是將它們嵌入到/**.
中。Javadoc寫在項目旁邊,沒有任何分隔換行符。請注意,任何import語句必須在類聲明之前。類聲明通常包括:
// import statements
/**
* @author 姓名 <address @ example.com>
* @version 1.6 (程序的当前版本号)
* @since 1.2 (加入该类时程序的版本号)
*/
public class Test {
// class body
}
對於方法,有如(1)所示的簡潔的一行描述來解釋項目的作用;接下來是(2)所示的更長的描述,該描述可以跨越多個段落並且是可有可無的;最後,第(3)部分列出接受的輸入參數和方法的返回值。所有的Javadoc都被視為HTML,因此多個段落部分由"<p>
"段落符號分隔。
/**
* 简短的单行描述。 (1)
* <p>
* 更长一些的描述可以写在这里。 (2)
* </p>
* 在HTML段落分隔的连续段落中还可以有更多注释。
*
* @param variable 描述文本。 (3)
* @return 描述文本。
*/
public int methodName (...) {
// method body with a return statement
}
與方法類似的註釋也可以用於變量的註釋,但省略了第(3)部分,這裏只包含了對變量的簡短描述:
/**
* 对变量的描述。
*/
private int debug = 0;
請注意,不建議[7]在單個文檔註釋中定義多個變量。這是因為Javadoc讀取每個變量並將它們分別放置到生成的HTML頁面,其中包含為所有字段複製的相同文檔註釋。
/**
* 点对 (x,y) 的水平和垂直距离
*/
public int x, y; // 避免这样的做法
相反,建議分別聲明和註釋每個變量:
/**
* 点的水平距离。
*/
public int x;
/**
* 点的垂直距离。
*/
public int y;
一部分可用的Javadoc標籤[8]列在下表中:
標籤&參數 | 用途 | 適用於 | 引入版本 |
---|---|---|---|
@author John Smith | 描述作者。 | 類、接口、枚舉 | |
{@docRoot} | 表示從任何生成的頁面生成的文檔的根目錄的相對路徑。 | 類、接口、枚舉、成員、方法 | |
@version 版本 | 提供軟件版本,每個類或接口最多一個。 | 類、接口、枚舉 | |
@since 起始 | 描述此功能首次存在的時間。 | 類、接口、枚舉、成員、方法 | |
@see 參考 | 提供指向其他文檔元素的連結。 | 類、接口、枚舉、成員、方法 | |
@param 名稱 描述 | 描述方法的一個參數。 | 方法 | |
@return 描述 | 描述返回值。 | 方法 | |
@exception 類 描述 @throws 類 描述 |
描述可能從此方法拋出的異常。 | 方法 | |
@deprecated 描述 | 描述一個過時的方法。 | 類、接口、枚舉、成員、方法 | |
{@inheritDoc} | 從被覆蓋的方法複製描述。 | 覆蓋方法 | 1.4.0 |
{@link 參考} | 連結到其他符號。 | 類、接口、枚舉、成員、方法 | |
{@linkplain 參考} | 與{@link}相同,但連結的標籤以純文本顯示,而不是代碼字體。 | 類、接口、枚舉、成員、方法 | |
{@value #STATIC_FIELD} | 返回靜態成員的值。 | 靜態成員 | 1.4.0 |
{@code 文本} | 在代碼字體中格式化文字文本,等同於<code> {@literal} </code>。 | 類、接口、枚舉、成員、方法 | 1.5.0 |
{@literal 文本} | 表示文本,隨附的文本被解釋為不包含HTML標記或嵌套的javadoc標記。 | 類、接口、枚舉、成員、方法 | 1.5.0 |
{@serial 文本} | 在Javadoc註釋中用於默認的可序列化字段。 | 成員 | |
{@serialData 文本} | 記錄writeObject()或writeExternal()方法寫入的數據。 | 成員、方法 | |
{@serialField 文本} | 記錄ObjectStreamField組件。 | 成員 |
下面是註釋一個方法的Javadoc示例。
/**
* 验证一步象棋的移动是否可行。
*
* <p>使用 {@link #doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)} 方法来移动棋子。
*
* @param theFromFile 被移动棋子的来源行
* @param theFromRank 被移动棋子的来源列
* @param theToFile 被移动棋子的目标行
* @param theToRank 被移动棋子的目标列
* @return 如果移动是可行的则返回true,否则返回false
* @since 1.0
*/
boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
// ...body
}
/**
* 移动一个棋子。
*
* @see java.math.RoundingMode
*/
void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
// ...body
}
- 文檔生成器的比較
- .Net的XML文檔註釋
Wikiwand in your browser!
Seamless Wikipedia browsing. On steroids.
Every time you click a link to Wikipedia, Wiktionary or Wikiquote in your browser's search results, it will show the modern Wikiwand interface.
Wikiwand extension is a five stars, simple, with minimum permission required to keep your browsing private, safe and transparent.