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