@ param
@ param標(biāo)簽可以歸檔方法或構(gòu)造器的某個單一參數(shù)，或者歸檔類、接口以及泛型方法的類型參數(shù)。在使用@ param標(biāo)簽時，我們應(yīng)該針對方法的每一個參數(shù)都使用一個該標(biāo)簽。每個段落的第一個詞會被當(dāng)作參數(shù)名，而余下的部分則會被當(dāng)作是對它的描述:

　　@param max The maximum number of words to read.

　　當(dāng)歸檔類型參數(shù)時，我們應(yīng)該在類型參數(shù)名兩邊加上<和>:

　　@param一e element type of this List

　　然而，類型參數(shù)通常并不需要顯式的文檔，因為它們的意義都很明顯。

@ see
@ see標(biāo)簽可以創(chuàng)建鏈接到其他javadoc文檔的交叉引用。我們可以在該標(biāo)簽的后面命名任何標(biāo)識符，盡管我們必須對它們進行充分的限定。例如，通?？梢允褂媚硞€類的成員的簡單名來命名它，但是如果該成員是一個重載方法，我們就必須通過列舉各個參數(shù)的類型來指定該方法的重載版本。我們可以使用未限定的名字來指定當(dāng)前包內(nèi)的接口或類，但必須使用完全限定名來指定其他包中的類型。我們可以通過在成員名的前面使用#來指定類型的成員。下面是所有有效的@ see標(biāo)簽格式:

　　@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的方法，該方法與文檔注釋自身位于同一個類或接口中，或者位于某個包圍類或包圍接口中，這樣的語法也可以應(yīng)用于構(gòu)造器和字段。第二種形式引用的是當(dāng)前包中的類或某個導(dǎo)人包中的類。第三種形式使用完全限定名引用了某個類。

　　后4種形式的@see引用的是成員，其中，前兩個是關(guān)于域(DECK-SIZ日和方法(getName)的形式。我們可以直接使用方法名，因為在Attr類中只定義了一個getName方法。后兩種形式引用的是Attr類的構(gòu)造器，其中一個構(gòu)造器接受的是字符串引元，而另一個構(gòu)造器接受的則是字符串和對象。當(dāng)構(gòu)造器或方法有重載版本時，我們必須指定想要引用的重載版本的引元。

　　接下來的@see形式將讀者引向了一個特定的包:com.magic.attro

　　最后的兩種形式使得我們可以引用其他的文檔。其中，前一個使用了來定義鏈接，后一個使用引號將文檔名括了起來。我們可以用這兩種形式將讀者引向其他文檔，例如完整的說明書。

　　對語言實體進行命名的@ see形式(除上面的最后兩種形式之外的所有形式)可以在實體的后面跟隨一個標(biāo)號(label)。在生成的文檔中，這種標(biāo)號的名字將會替代實體的名字。例如:

　　@ see #getNameAttribute Names

　　將創(chuàng)建一個指向getName的文檔的鏈接，但它所顯示的文本是”Attribute Names”而不是"getName"。通常我們應(yīng)該使用成員的真實名字，但這里所展示的特性偶爾也會很有用。

最新評論