java文件註釋規範：javadoc標籤（二）
javadoc標籤必須從一行的開頭（在任何前導空格和可選的星號之後）開始，否則將被視為普通文字。 按照慣例，具有相同名稱的標籤被組合在一起（標籤大小寫敏感）。 例如，將所有@see標記放在一起。標籤可以分為：
- 塊標籤：只能放在主要描述部分後面的標籤部分。 塊標籤的格式為：@tag。
- 內聯標記：可以放在主要描述中的任何位置或塊標籤的註釋中。 內聯標記用花括號標記：{@ tag}。
現有的javadoc標籤（截至jdk1.5）：
@author 名字（文字） 當使用-author選項時，以指定的名字（文字）新增一個“Author”條目到生成的文件中。 文件註釋可以包含多個@author標籤。可以為每個@author
@deprecated 被棄用文字 注意：從JDK 5.0開始，可以使用@Deprecated註解來標記棄用程式元素。 新增一個標記此API不應再使用的註釋（即使它可能仍然有效）。Javadoc工具把被棄用文字移動到主要描述之前，將其置為斜體字，並在其前面加上一個粗體警告：“Deprecated”。此標籤在所有文件註釋中都有效：概述，包，類，介面，建構函式，方法和欄位。被棄用文字
- 對於Javadoc 1.2及更高版本，請使用{@link}標記。這會在您想要的位置建立內聯連結。例如：
/**
* @deprecated自JDK 1.1起，替換為{@link #setBounds（int，int，int，int）}
*/- 對於Javadoc 1.1，標準格式是為每個@deprecated標籤建立一個@see標籤（但是不能“內聯”）。
{@code 文字}
等同於<code> {@ literal} </ code>。 以程式碼字型顯示文字而不將文字解釋為HTML標籤或巢狀的javadoc標籤。這使您可以在文件註釋中使用尖括號（<和>）而不是HTML實體（＆lt;和＆gt;），例如引數型別（<Object>），不等式（3 <4）或箭頭（ < - ）。例如，doc註釋文字：
{@code A <B> C} 在生成的HTML頁面中的顯示不變： A <B> C <B>不會被解釋為粗體，並且以程式碼字型顯示。 如果您想要非程式碼字型的同樣的功能，請使用{@literal}。
{@docRoot} 表示從任何生成的頁面到生成的文件（目標）根目錄的相對路徑。當您想要包含一個要在所有生成的頁面中都引用的檔案（例如版權頁面或公司徽標）時，它非常有用。在每頁底部都連結到版權頁面很常見。{@docRoot}標籤可以在命令列和文件註釋中使用：在所有文件註釋中都有效：概述，包，類，介面，建構函式，方法和欄位，包括任何標籤的文字部分（例如@return，@param和@deprecated）。
- 在命令列上，在定義頁首/頁尾/底部的地方：
javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>' 注意：在make檔案中以這種方式使用{@docRoot}時，某些makefile程式需要對括號{}字元進行特殊的轉義。例如，在Windows上執行的Inprise MAKE 5.2版需要雙括號：{{@ docRoot}}。它還需要雙引號（而不是單引號）將諸如-bottom之類的選項的引數括起來（同時省略了href引數周圍的引號）。 在文件註釋中：
/**
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
*/需要此標籤的原因是由於生成的文件位於分層的目錄中，與子包的數量一樣深。這個表示式： <a href="{@docRoot}/copyright.html"> 在java/lang/Object.java檔案中會解析為：<a href="../../copyright.html">；在java/lang/ref/Reference.java檔案中會解析為：<a href="../../../copyright.html">
@exception 類名 描述@exception標籤是@throws的同義詞。
{@inheritDoc} 從“最近的”可繼承類或可實現的介面繼承（複製）註釋文件到當前doc註釋中（位於此標籤所在位置）。這允許您在繼承樹的更高處編寫更一般的註釋，也使您可以在複製的文本週圍編寫註釋。此標籤僅在文件註釋中的以下位置有效：
- 在方法的主要描述塊中。在這種情況下，主要描述從繼承層次結構中的類或介面複製。
- 在方法的@return，@param和@throws標籤的文字引數中。在這種情況下，標籤文字將從繼承層次結構中的相應標籤複製
請注意，如果缺少此標記，則根據該部分中描述的規則決定是否自動繼承註釋。
{@link package.class＃member label} 插入帶有可見文字標籤的內嵌連結（該連結指向引用類的指定包名，類名或成員名的文件）。此標籤在所有文件註釋中都有效：概述，包，類，介面，建構函式，方法和欄位，包括任何標籤的文字部分（例如@return，@ param和@deprecated）。 此標籤與@see非常相似：兩者都需要相同的引用，並且對package.class #member和label接受完全相同的語法。主要區別在於{@link}生成了一個內聯連結而不是將連結放在“See Also”部分。如果你需要用在label中使用“}”，請使用 HTML實體標記}，}句子中允許的{@link}標籤數量沒有限制。例如，這是一個引用getComponentAt（int，int）方法的註釋：
Use the {@link #getComponentAt(int, int) getComponentAt} method.
由此，標準doclet將生成以下HTML（假設它引用同一包中的另一個類）：
Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.
它在網頁上顯示為：Use the getComponentAt method。您可以使用-link選項擴充套件{@link}以連結到沒有被文件記錄（documented）的類。
{@linkplain package.class＃member label} 與{@link}相同，但連結的label以純文字顯示，而不是程式碼字型。label是純文字時很有用。例： Refer to {@linkplain add() the overridden method}. 這將顯示為： Refer to the overridden method.
{@literal 文字}
顯示文字而不將文字解釋為HTML標籤或巢狀的javadoc標籤。這使您可以在文件註釋中使用尖括號（<和>） 而不是HTML實體（＆lt;和＆gt;），比如引數型別（<Object>），不等式（3 <4）或箭頭（ < - ）。例如，文件註釋文字： {@literal A <B> C} 在瀏覽器中生成的HTML頁面中顯示不變： A <B> C。如果您想要相同的功能但使用程式碼字型的文字，請使用{@code}。
@param 引數名 描述 新增一個有指定引數名的“引數”。引數名後緊跟對引數部分的具體描述。描述可以跨多行。此標記僅在方法，建構函式或類的文件註釋中有效。引數名可以是方法或建構函式中的引數名，也可以是類，方法或建構函式的型別引數名。在此引數名周圍使用尖括號指定使用型別引數。
類的型別引數示例：
/**
* @param <E> Type of element stored in a list
*/
public interface List<E> extends Collection<E> {
}
方法的型別引數例項：
/**
* @param string the string to be converted
* @param type the type to convert the string to
* @param <T> the type of the element
* @param <V> the value of the element
*/
<T, V extends T> V convert(String string, Class<T> type) {
}@return 描述 新增帶有描述文字的“Returns”部分。該文字應描述返回型別和允許的值範圍。此標記僅在方法的文件註釋中有效。
@see 引用 新增“See Also”標題，其中包含指向引用的連結或文字條目。文件註釋可以包含任意數量的@see標籤，這些標籤都被歸入同一標題下。 @see標籤有三種變體，下面的第三種形式是最常見的。此標記在任何文件註釋中都有效：概述，包，類，介面，建構函式，方法或欄位。要將句子中的內嵌連結插入包，類或成員，請參閱{@link}。
- @see "字串"
新增字串的文字條目（不會生成連結）。該字串是書籍或其他（URL不可用的）資訊的引用。 Javadoc工具通過查詢雙引號（"）作為第一個字元來區分此情況。例如： @see "Java程式語言" 這會生成以下文字：
See Also: "The Java Programming Language"
- @see <a href="URL#value">標籤</a>
新增URL＃value定義的連結。 URL＃值是相對或絕對URL。 Javadoc工具通過查詢小於號（<）作為第一個字元來區別於其他情況。例如： @see <a href="spec.html#section"> Java Spec </a> 這會生成一個連結： See Also: Java Spec
- @see package.class＃member label
新增帶有可見文字標籤的連結，該連結指向所引用的Java Language中指定的name的文件。label是可選的。如果省略，則name（package.class＃member 部分）作為可見文字顯示，並將適當的縮短 （ 請參閱下面：名字如何顯示）。使用-noqualifier將全域性地從可見文字中刪除包名。如果希望可見文字與自動生成的可見文字不同，請使用label。 僅在版本1.2中，只有名字而不是label會自動出現在<code> HTML標籤中；從1.2.2開始，<code>始終包含在可見文本週圍，無論是否使用label。package.class #member是被引用的任何有效程式元素名：包，類，介面，建構函式，方法或欄位名，成員名前面的字元應該是雜湊字元（＃）。該class 表示任何頂級或巢狀類或介面。該member表示任何建構函式，方法或欄位（包括巢狀類或介面）。如果此名位於被文件記錄（documented）的類中，則Javadoc工具將自動建立指向它的連結。要建立指向外部引用類的連結，請使用-link選項。使用其他兩個@see的變體中來引用不屬於引用類name的文件。（下面的“定製名字”中下更詳盡地描述了該引數。）
label是可選文字，作為連結的標籤顯示。label可以包含空格。空格是package.class #member和label之間的分隔符（不包括括號內的空格，因此可以在方法中的引數之間使用空格）。示例：
/**
* @see String#equals(Object) equals
*/標準doclet將生成這樣的HTML：
<dl>
<dt><b>See Also:</b>
<dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a>
</dl>在瀏覽器中看起來像這樣，label是可見的連結文字： See Also: equals
定製名字
這裡的package.class#member （名字）可以是完全限定的，例如 java.lang.String#toUpperCase() ，也可以不是，例如String#toUpperCase()或#toUpperCase()。如果沒有完全限定，Javadoc工具使用普通的Java編譯器搜尋順序來查詢它，下面在@see的搜尋順序中將詳盡描述。名字可以在括號內包含空格（例如方法引數之間）。
當然，提供更短的“部分限定”名字的優點是它們的型別更短，使得原始碼中的雜亂程度更低。下表顯示了名稱的不同形式，其中Class可以是類或介面，Type可以是類，介面，陣列或基本型別，方法可以是方法或建構函式。
Typical forms for @see package.class#member |
||
Referencing a member of the current class@see #field@see #method(Type, Type,...)@see #method(Type argname, Type argname,...)@see #constructor(Type, Type,...)@see #constructor(Type argname, Type argname,...)Referencing another class in the current or imported packages@see Class#field@see Class#method(Type, Type,...)@see Class#method(Type argname, Type argname,...)@see Class#constructor(Type, Type,...)@see Class#constructor(Type argname, Type argname,...)@see Class.NestedClass@see ClassReferencing an element in another package (fully qualified)@see package.Class#field@see package.Class#method(Type, Type,...)@see package.Class#method(Type argname, Type argname,...)@see package.Class#constructor(Type, Type,...)@see package.Class#constructor(Type argname, Type argname,...)@see package.Class.NestedClass@see package.Class@see package |
||
上表中的注意事項： 第一種形式（沒有類或包）將導致Javadoc工具僅搜尋當前類的層次結構。它將找到當前類或介面或者其超類或超介面之一，或其封閉的類或介面之一的一個成員（搜尋步驟1-3）。它不會搜尋當前包或其他包的其餘部分（搜尋步驟4-5）。
如果輸入沒有括號形式的任何方法或建構函式，例如getValue，並且如果沒有相同名字的欄位，則Javadoc工具將正確建立指向它的連結，不過會列印一條警告訊息，提醒您新增括號和引數。如果此方法被過載，Javadoc工具將連結到其搜尋遇到的第一個方法，該方法將是不確定的。
不管應用哪種形式，巢狀類必須指定為outer.inner，而不僅僅是inner。 如上所述，雜湊字元（＃）而不是點（.）將成員與其類分開。這使得Javadoc工具能夠解決歧義，因為點還分隔了類，巢狀類，包和子包。但是，Javadoc工具是寬鬆的，如果你確定不存在歧義，它會正確地解析一個（.），不過它會列印一個警告。
@see的搜尋順序
Javadoc工具將處理出現在原始檔（.java），包檔案（package.html或package-info.java）或概述檔案（overview.html）中的@see標記。在後兩個檔案中，必須為@see提供完全限定的名字。在原始檔中，您可以指定完全限定或部分限定的名字。
當Javadoc工具在.java檔案中遇到非完全限定的@see標籤時，它會按照與Java編譯器相同的搜尋順序搜尋指定的名字（不同的是，Javadoc工具不會檢測某些名稱空間歧義，因為它假設原始碼沒有這些錯誤）。Javadoc工具通過所有相關和匯入的類和包搜尋該名字。它按以下順序搜尋：
- 當前的類或介面
- 任何封閉（enclosing）的類和介面，優先搜尋最近的
- 任何超類和超介面，優先搜尋最近的
- 當前包
- 任何匯入的包，類和介面，按import語句的順序搜尋
Javadoc工具繼續通過步驟1-3遞迴搜尋它遇到的每個類，直到找到匹配的為止。也就是說，在搜尋當前類及其封閉類E之後，它將在搜尋E的封閉類之前搜尋E的超類。在步驟4和5中，Javadoc工具不會以任何特定的順序搜尋包中的類或介面（該順序取決於特定的編譯器）。在第5步中，Javadoc工具會在java.lang中查詢，因為它會被所有程式自動匯入。
Javadoc工具不一定在子類中查詢，也不會在其他包中查詢，即使它們的文件也在同一次執行中生成。例如，如果@see標籤位於java.awt.event.KeyEvent類中並引用java.awt包中的名字，則javadoc不會查詢該包，除非該類匯入了它。
名字如何顯示
如果省略label，則將顯示package.class.member。 通常，它相對於當前的類和包適當地縮短。Javadoc工具只顯示必要的最小名字。 例如，如果String.toUpperCase()方法包含對同一個類的成員和另一個類的成員的引用，則僅在後一種情況下顯示類名，如下表所示。
Use -noqualifier to globally remove the package names.
| Type of Reference | Example in String.toUpperCase() |
Displays As |
|---|---|---|
@see tag refers to member of the same class, same package |
@see String#toLowerCase() |
toLowerCase()
(omits the package and class names) |
@see tag refers to member of a different class, same package |
@see Character#toLowerCase(char) |
Character.toLowerCase(char)
(omits the package name, includes the class name) |
@see tag refers to member of a different class, different package |
@see java.io.File#exists() |
java.io.File.exists()
(includes the package and class names) |
@see的例子 右邊的註釋顯示瞭如果@see標記位於另一個包中的類（如java.applet.Applet）中，將如何顯示該名稱。
See also:
@see java.lang.String // String
@see java.lang.String The String class // The String class
@see String // String
@see String#equals(Object) // String.equals(Object)
@see String#equals // String.equals(java.lang.Object)
@see java.lang.Object#wait(long) // java.lang.Object.wait(long)
@see Character#MAX_RADIX // Character.MAX_RADIX
@see <a href="spec.html">Java Spec</a> // Java Spec
@see "The Java Programming Language" // "The Java Programming Language" 可以使用-link選項擴充套件@see以連結到未被文件記錄的類。
@serial 欄位描述|include|exclude 用於預設的可序列化欄位的文件註釋。 可選的欄位描述應解釋欄位的含義並列出可接受的值。欄位描述可以跨多行。標準doclet將此資訊新增到序列化表單頁面。如果可序列化欄位在類可序列化之後的某個時間被新增到類中，則應在其主要描述中新增一個語句以標識它的新增版本。include和exclude引數標識是否應在序列化表單頁面中包含或排除類或包。他們以如下方式工作：
除非該類（或其包）標記為@serial exclude，否則將包含實現Serializable的公共類或受保護類。 除非該類（或其包）標記為@serial include，否則將排除實現Serializable的私有或包私有類。 例如：javax.swing包標記為@serial exclude（在package.html或package-info.java中）。公共類java.security.BasicPermission標記為@serial exclude。 package-private類java.util.PropertyPermissionCollection標記為@serial include。
類級別的@serial標籤會在包級別覆蓋@serial。
@serialField 欄位名 欄位型別 欄位描述 記錄可序列化類的serialPersistentFields成員的ObjectStreamField元件。每個ObjectStreamField元件都應使用一個@serialField標籤。
@serialData 資料描述 資料描述以序列化形式記錄了資料型別和順序。具體來說，此資料包括writeObject方法寫入的可選資料以及Externalizable.writeExternal方法寫入的所有資料（包括基本類）。@serialData標記可以在writeObject，readObject，writeExternal，readExternal，writeReplace和readResolve方法的文件註釋中使用。
@since 文字 使用指定的文字向生成的文件新增“Since”標題。該文字沒有特殊的內部結構。此標籤在任何文件註釋中都有效：概述，包，類，介面，建構函式，方法或欄位。此標記表示自文字指定的軟體版本以來，此更改或功能已存在。例如： @since 1.5 在Java平臺中的原始碼裡，此標籤代表Java平臺API規範的版本（不一定在將其新增到參考實現時）。允許使用多個@since標籤，類似於多個@author標籤。如果prgram元素被多個API使用，你可以使用多個標籤。
@throws 類名 描述@throws和@exception標籤是同義詞。使用類名和描述文字向生成的文件新增“throws”子標題。類名是方法可能丟擲的異常的名字。此標籤僅在方法或建構函式的文件註釋中有效。如果未完全指定此類，則Javadoc工具使用搜索順序查詢此類。對於相同或不同的異常，可以在給定的文件註釋中使用多個@throws標記。 為確保記錄所有已檢查的異常，如果throws子句中的異常不存在@throws標籤，則Javadoc工具會自動將該異常新增到HTML輸出（沒有描述），就像使用@throws標籤記錄了一樣。只有在重寫方法中顯式聲明瞭異常時，才會將@throws註釋從被重寫的方法複製到子類。從介面方法複製到實現方法也是如此。您可以使用{@inheritDoc}強制@throws繼承文件。
{@value package.class #field} 當在靜態欄位的doc註釋中使用{@value}（沒有任何引數）時，它會顯示該常量的值：
/**
* The value of this constant is {@value}.
*/
public static final String SCRIPT_START =“<script>”當與任何文件註釋中的引數package.class #field一起使用時，它會顯示指定常量的值：
/**
* Evaluates the script starting with {@value #SCRIPT_START}.
*/
public String evalScript(String script) {
}引數package.class #field採用與@see的引數相同的形式，但該成員必須是靜態欄位。這些常量的值也顯示在“常量欄位值”頁面上。
@version 版本文字 使用-version選項時，將指定版本文字的“Version”子標題新增到生成的文件中。 此標籤用於儲存此程式碼所屬軟體的當前版本號（與@since相反，後者儲存引入此程式碼的版本號）。 版本文字沒有特殊的內部結構。文件註釋可能包含多個@version標記。 如果有意義，您可以為每個@version標籤指定一個版本號，或為每個標籤指定多個版本號。 在前一種情況下，Javadoc工具在名稱之間插入逗號（，）和空格。 在後一種情況下，只需將整個文字複製到生成的文件而不進行解析。 因此，如果需要使用除逗號之外的其他分隔符，則可以每行使用多個版本號。
標籤可以在何處使用
注意：@ see，@ since，@ deprecated，{@ link}，{@ linkplain}和{@docroot}可用於所有文件註釋。
- 概述文件註釋標籤
注意：{@link}標籤在版本1.2中的概述文件中有bug - 文字正確顯示但沒有連結。 {@docRoot}標籤目前不適用於概述文件。
- 包文件註釋標籤
@serial標籤只能在此處使用必須include或exclude引數。
- 類和介面文件註釋標籤
@serial標籤只能在此處使用必須include或exclude引數。
例如：
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version %I%, %G%
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}- 欄位文件註釋標籤
例如：
/**
* The X-coordinate of the component.
*
* @see #getLocation()
*/
int x = 1263732;- 建構函式和方法文件註釋標籤
except for @return, which cannot appear in a constructor, and {@inheritDoc}, which has certain restrictions. The @serialData tag can only be used in the doc comment for certain serialization methods.
例如：
/**
* Returns the character at the specified index. An index
* ranges from <code>0</code> to <code>length() - 1</code>.
*
* @param index the index of the desired character.
* @return the desired character.
* @exception StringIndexOutOfRangeException
* if the index is not in the range <code>0</code>
* to <code>length()-1</code>.
* @see java.lang.Character#charValue()
*/
public char charAt(int index) {
...
}References
4. Cay S. Horstmann,Gary Cornell, Core Java volume I,Ninth Edition