跳至內容

Javadoc

維基百科,自由的百科全書

Javadoc(最初是JavaDoc[1]是由Sun MicrosystemsJava語言(現在由甲骨文公司擁有)創建的文檔生成器,用於從Java源代碼生成HTML格式的API文檔,HTML格式用於增加將相關文檔鏈接在一起的便利性。[2]

Javadoc使用的「doc comments」格式[3] 是記錄Java類的事實上的行業標準。一些IDE[4]IntelliJ IDEANetBeansEclipse,可以自動生成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. 第一段是對所記錄方法的描述。
  2. 在描述之後是不同數量的描述性標籤,表示:
    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
}

參見

參考文獻

  1. ^ 現在寫作『Javadoc』,參見[1]頁面存檔備份,存於網際網路檔案館)。最早寫作『JavaDoc』,參見[2]頁面存檔備份,存於網際網路檔案館
  2. ^
  3. ^ javadoc - The Java API Documentation Generator. Sun Microsystems. [2011-09-30]. (原始內容存檔於2020-05-05). 
  4. ^ IntelliJ IDEA頁面存檔備份,存於網際網路檔案館), NetBeans頁面存檔備份,存於網際網路檔案館) and Eclipse頁面存檔備份,存於網際網路檔案館
  5. ^ How to Write Doc Comments for the Javadoc Tool. Sun Microsystems. [2011-09-30]. (原始內容存檔於2020-04-29). .
  6. ^ Bill Venners, James Gosling.... Visualizing with JavaDoc. artima.com. 2003-07-08 [2013-01-19]. (原始內容存檔於2018-12-15). When I did the original JavaDoc in the original compiler, even the people close around me pretty soundly criticized it. And it was interesting, because the usual criticism was: a good tech writer could do a lot better job than the JavaDoc does. And the answer is, well, yeah, but how many APIs are actually documented by good tech writers? And how many of them actually update their documentation often enough to be useful? 
  7. ^ Java Platform, Standard Edition Tools Reference for Oracle JDK on Solaris, Linux, and OS X, Release 8. Section "Multiple-Field Declarations". [20 Dec 2017]. (原始內容存檔於2020-11-05). 
  8. ^