@ param
@ param標簽可以歸檔方法或構造器的某個單一參數,或者歸檔類、接口以及泛型方法的類型參數。在使用@ param標簽時,我們應該針對方法的每一個參數都使用一個該標簽。每個段落的第一個詞會被當作參數名,而余下的部分則會被當作是對它的描述:
1
|
@param max The maximum number of words to read. |
當歸檔類型參數時,我們應該在類型參數名兩邊加上<和>:
1
|
@param 一e element type of this List |
然而,類型參數通常并不需要顯式的文檔,因為它們的意義都很明顯。
@ see
@ see標簽可以創建鏈接到其他javadoc文檔的交叉引用。我們可以在該標簽的后面命名任何標識符,盡管我們必須對它們進行充分的限定。例如,通??梢允褂媚硞€類的成員的簡單名來命名它,但是如果該成員是一個重載方法,我們就必須通過列舉各個參數的類型來指定該方法的重載版本。我們可以使用未限定的名字來指定當前包內的接口或類,但必須使用完全限定名來指定其他包中的類型。我們可以通過在成員名的前面使用#來指定類型的成員。下面是所有有效的@ see標簽格式:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
@see #getName @see Attr @see com.magic.attr.Attr @see com.magic.attr.Deck#DECK-SIZE @see com.magic.attr.Attr#getName @see com.magic.attr.Attr#Attr(String) @see com.magic.attr.Attr#Attr(String,Object) @see com.magic.attr @see Attribute Specification @see "The Java Developer's Almanac" |
第一種形式所指的是名為getName的方法,該方法與文檔注釋自身位于同一個類或接口中,或者位于某個包圍類或包圍接口中,這樣的語法也可以應用于構造器和字段。第二種形式引用的是當前包中的類或某個導人包中的類。第三種形式使用完全限定名引用了某個類。
后4種形式的@see引用的是成員,其中,前兩個是關于域(DECK-SIZ日和方法(getName)的形式。我們可以直接使用方法名,因為在Attr類中只定義了一個getName方法。后兩種形式引用的是Attr類的構造器,其中一個構造器接受的是字符串引元,而另一個構造器接受的則是字符串和對象。當構造器或方法有重載版本時,我們必須指定想要引用的重載版本的引元。
接下來的@see形式將讀者引向了一個特定的包:com.magic.attro
最后的兩種形式使得我們可以引用其他的文檔。其中,前一個使用了來定義鏈接,后一個使用引號將文檔名括了起來。我們可以用這兩種形式將讀者引向其他文檔,例如完整的說明書。
對語言實體進行命名的@ see形式(除上面的最后兩種形式之外的所有形式)可以在實體的后面跟隨一個標號(label)。在生成的文檔中,這種標號的名字將會替代實體的名字。例如:
1
|
@ see #getNameAttribute Names |
將創建一個指向getName的文檔的鏈接,但它所顯示的文本是”Attribute Names”而不是"getName"。通常我們應該使用成員的真實名字,但這里所展示的特性偶爾也會很有用。