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

　　@param max The maximum number of words to read.

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

　　@param一e element type of this List

　　然而，類(lèi)型參數(shù)通常并不需要顯式的文檔，因?yàn)樗鼈兊囊饬x都很明顯。

@ see
@ see標(biāo)簽可以創(chuàng)建鏈接到其他javadoc文檔的交叉引用。我們可以在該標(biāo)簽的后面命名任何標(biāo)識(shí)符，盡管我們必須對(duì)它們進(jìn)行充分的限定。例如，通?？梢允褂媚硞€(gè)類(lèi)的成員的簡(jiǎn)單名來(lái)命名它，但是如果該成員是一個(gè)重載方法，我們就必須通過(guò)列舉各個(gè)參數(shù)的類(lèi)型來(lái)指定該方法的重載版本。我們可以使用未限定的名字來(lái)指定當(dāng)前包內(nèi)的接口或類(lèi)，但必須使用完全限定名來(lái)指定其他包中的類(lèi)型。我們可以通過(guò)在成員名的前面使用#來(lái)指定類(lè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的方法，該方法與文檔注釋自身位于同一個(gè)類(lèi)或接口中，或者位于某個(gè)包圍類(lèi)或包圍接口中，這樣的語(yǔ)法也可以應(yīng)用于構(gòu)造器和字段。第二種形式引用的是當(dāng)前包中的類(lèi)或某個(gè)導(dǎo)人包中的類(lèi)。第三種形式使用完全限定名引用了某個(gè)類(lèi)。

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

　　接下來(lái)的@see形式將讀者引向了一個(gè)特定的包:com.magic.attro

　　最后的兩種形式使得我們可以引用其他的文檔。其中，前一個(gè)使用了來(lái)定義鏈接，后一個(gè)使用引號(hào)將文檔名括了起來(lái)。我們可以用這兩種形式將讀者引向其他文檔，例如完整的說(shuō)明書(shū)。

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

　　@ see #getNameAttribute Names

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

最新評(píng)論