Javadoc：參數和返回需要明確的類型描述

Question

當Javadoc'ing時，我不知道您是否應該明確說明參數的類型是String還是int。例如

/** 
* This method does something 
* @param foo an object of type Foo 
* @param abc the number of doors, of type int 
* @return the number of windows, of type int 
*/ 
public int doSomething(Foo foo, int abc) { 
    // Do something 
} 

我使用Eclipse，所以當我看一個的Javadoc的用戶端，任何事物都有一個類型的描述，和Eclipse告訴我，當我使用了錯誤類型的參考。

那麼，我應該如上所述包含類型描述，還是Javadoc /編譯器爲我處理這些？

Answer 1

不，沒有必要，JavaDoc工具解析Java代碼並從那裏獲取類型。

本文甲骨文的Java網站上可能是有用的：How to Write Doc Comments for the Javadoc Tool

那篇文章的@param part：

的@param標記後面的名字（而非數據類型）參數，然後是參數的描述。按照慣例，描述中的第一個名詞是參數的數據類型。 （像「a」，「an」和「the」這樣的文章可以在名詞前面。）對於通常省略數據類型的基本int進行例外。在名稱和描述之間可以插入額外的空格，以便將描述排列在一個塊中。在描述之前不應插入虛線或其他標點符號，因爲Javadoc工具會插入一個破折號。

參數名稱按照慣例小寫。數據類型以小寫字母開頭，以指示對象而不是類。

...其中聽起來喜歡它不同意我上面的聲明。這只是寫不好，因爲它的例子然後給出了明確：

@param ch the character to be tested

@param observer the image observer to be notified

@param x the x-coordinate, measured in pixels

它也清楚the detailed examples。