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

@ param
@ param標籤可以歸檔方法或建構器的某個單一參數，或是歸檔類別、介面以及泛型方法的型別參數。在使用@ param標籤時，我們應該針對方法的每一個參數都使用一個該標籤。每個段落的第一個字會被當作參數名，而餘下的部分則會被當作是對它的描述:

@param max The maximum number of words to read.

　　當歸檔類型參數時，我們應該在類型參數名兩邊加上:

@param一e element type of this List

　　然而，類型參數通常並不需要明確的文檔，因為它們的意義都很明顯。

@ see
@ see標籤可以建立連結到其他javadoc文件的交叉引用。我們可以在該標籤的後面命名任何標識符，儘管我們必須對它們進行充分的限定。例如，通常可以使用某個類別的成員的簡單名稱來命名它，但是如果該成員是一個重載方法，我們就必須透過列舉各個參數的類型來指定該方法的重載版本。我們可以使用未限定的名字來指定目前包內的介面或類，但必須使用完全限定名來指定其他包中的類型。我們可以透過在成員名的前面使用#來指定類型的成員。以下是所有有效的@ see標籤格式:

@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方法。載版本時，我們必須指定想要引用的重載版本的引元。可以引用其他的文檔。實體進行命名的@ see形式(除上面的最後兩種形式之外的所有形式)可以在實體的後面跟隨一個標號(label)。 。的特性偶爾也會很有用。