Javadoc - Wikiwand

Javadoc（最初是JavaDoc）^[1]是由Sun Microsystems為Java語言（現在由甲骨文公司擁有）創建的文檔生成器，用於從Java原始碼生成HTML格式的API文檔，HTML格式用於增加將相關文檔連結在一起的便利性。^[2]

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開發工具包的每個新版本上都會更新。

技術架構

Javadoc註釋結構

通過標準多行註釋標記/* and */從代碼中引發Javadoc註釋。起始標記（稱為開始 - 註釋分隔符）具有額外的星號，如/**中所示。

第一段是對所記錄方法的描述。
在描述之後是不同數量的描述性標籤，表示：
1. 方法的參數（@param）
2. 方法返回的內容（@return）
3. 方法可能拋出的任何異常（@exception）
4. 其他不太常見的標籤，如 @see （「另見」標籤）

Javadoc概覽

編寫文檔註釋的基本結構是將它們嵌入到/**.中。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標籤表

一部分可用的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
}

參見

文檔生成器的比較（英語：Comparison of documentation generators）
.Net的XML文檔註釋（英語：C Sharp syntax）

參考文獻

Loading content...

Loading related searches...

Wikiwand - on

Seamless Wikipedia browsing. On steroids.