Javadoc
| 導航 Javadoc & 註解 主題： |
Java 允許使用者使用特定的註釋語法來記錄類和成員。
文件註釋用斜槓-星號-星號和星號-斜槓（即 /** ... */）包圍。文件採用 HTML 格式。
|
程式碼清單 8.1：Example.java
/**
* A class to give an <b>example</b> of HTML documentation.
*/
public class Example {
/** ...Documentation of a member with the type integer named example... */
public int example;
}
|
文件註釋放置在註釋實體（類、建構函式、方法、欄位）的正上方。
在文件註釋中，第一部分是用 HTML 格式描述的文字。第二部分是名稱以“@”符號開頭的特殊屬性列表
|
程式碼段 8.1：文件註釋。
/**
* Get the sum of two integers.
* @param a The first integer number.
* @param b The second integer number.
* @return The value of the sum of the two given integers.
*/
public int sum(int a, int b) {
return a + b;
}
|
獲取兩個整數的總和。- sum 方法的描述。
@param a 第一個整數。- 方法引數 a 的描述屬性。
@param b 第二個整數。- 方法引數 b 的描述屬性。
@return 給定兩個整數的總和的值。- 方法返回值的描述屬性。
以下是非詳盡的特殊屬性列表
| 屬性和語法 | 在... 的註釋中 | 描述 |
|---|---|---|
| @author 作者 | 類 | 類的作者姓名。 |
| @version 版本 | 類 | 類的版本。 |
| @deprecated 描述 | 類、建構函式、方法、欄位 | 將實體標記為已棄用（舊版本），說明原因以及用什麼替換它。 如果用此屬性標記為已棄用的實體，編譯器會發出警告。 |
| @see 引用 | 類、建構函式、方法、欄位 | 在“另請參見”部分新增連結。 |
| @param id 描述 | 建構函式和方法 | 描述方法引數。 |
| @return 描述 | 方法 | 描述方法返回值。 |
| @exception 型別 描述 | 建構函式和方法 | 描述丟擲指定型別異常的原因（throws 子句）。 |
另請參見 註解，自 Java 5 起。
JDK 提供了一個名為 javadoc 的工具，允許生成良好註釋類的文件。不帶引數的 javadoc 命令給出命令的完整語法。
例如：對於名為 Example 的類，定義在名為 org.wikibooks.en 的包中，檔名為 C:\ProgJava\org\wikibooks\en\Example.java
|
|
程式碼清單 8.2：Example.java
package org.wikibooks.en;
/**
* An example class.
*/
public class Example {
/**
Get the sum of two integers.
@param a The first integer number.
@param b The second integer number.
@return The value of the sum of the two given integers.
*/
public int sum(int a, int b) {
return a + b;
}
}
|
可以使用以下命令在特定資料夾（例如 C:\ProgDoc）中生成文件
|
命令 8.1：文件生成
$ javadoc -locale en_US -use -classpath C:\ProgJava -sourcepath C:\ProgJava -d C:\ProgDoc org.wikibooks.en |
該命令的選項描述如下
-locale en_US- 以美式英語生成文件。
-use- 建立有關類和包使用的頁面。
-classpath C:\ProgJava- 編譯類（*.class）的路徑。
-sourcepath C:\ProgJava- 原始碼類（*.java）的路徑。
-d C:\ProgDoc- 必須生成文件的路徑。
org.wikibooks.en- 要記錄的包的名稱。可以指定多個包，或一個或多個類名，只記錄這些類。
包的描述頁面會從名為 package.html 的檔案中複製描述文字，該檔案應放置在給定的資料夾中。在本例中，應在檔案 C:\ProgJava\org\wikibooks\en\package.html 中記錄包。
自 Java 5[1] 起，package.html 檔案可以用名為 package-info.java 的特殊 Java 檔案替換，該檔案只包含由文件註釋字首的包宣告。
|
|
程式碼清單 8.3：C:\ProgJava\org\wikibooks\en\package-info.java
/**
* This fake package is used to illustrate the Java wikibook.
* at <i>en.wikibooks.org</i>.
*/
package org.wikibooks.en;
|
