小議Java中@param注解與@see注解的作用

更新時(shí)間：2015年12月21日 17:44:28 作者：爪哇小博

這篇文章主要介紹了Java中@param注解與@see注解的作用,注解的功能類似于通常代碼中的注釋,需要的朋友可以參考下

@ param
@ param標(biāo)簽可以歸檔方法或構(gòu)造器的某個(gè)單一參數(shù)，或者歸檔類、接口以及泛型方法的類型參數(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)歸檔類型參數(shù)時(shí)，我們應(yīng)該在類型參數(shù)名兩邊加上<和>:

　　@param一e element type of this List

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

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

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

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

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

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