Java文檔 - @return和@param

Question

我在想如何使用@return和@param來編寫代碼...？我有點猜測，我會做類似

@return(whatever the method is returning) 
@param(parameters that the method is taking in) 

我會不得不在更多的描述後？另外，是否有太多的文檔？

Answer 1

爲什麼不從查找什麼JavaDocs開始？

http://en.wikipedia.org/wiki/Javadoc

的它們是如何使用的一個例子是這樣的。

/** 
* Gets the id of the player. 
* 
* @param someParam you'd put a description of the parameter here. 
* @return the id of the object. 
*/ 
public int getId(int someParam) { 
    return this.id; 
} 

Answer 2

這是你所談論的Javadoc：

/** 
* Subject line 
* 
* <p>Description of the method with optional {@code code} and {@link Object links to Javadoc} 
* </p> 
* 
* <pre> 
* raw input 
* </pre> 
* 
* @param foo first arg 
* @return a bar 
* @throws SomeException if bar goes wrong 
* @see someOtherMethod() 
* @since 2.2.2 
* @author me 
*/ 
int doSomething(final int foo) 
    throws SomeException 
{ 
    // etc 
} 

Javadoc工具（和使用各種構建系統，如gradle產出和Maven這一工具的目標）會產生從HTML文件。

之後我需要做更多描述嗎？

在此之前，事實上，作爲一個約定。只有你認爲有必要。

另外，是否有太多的文檔？

是的。

Answer 3

這些東西都是javadoc標籤。 http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

但基本的例子，你所提到的這兩個看起來就像這樣：如何使用他們，你可以在這裏找到完整的參考

/** 
* Adds two values. 
* 
* @param operand1 - first numeric value for the ADD operation 
* @param operand2 - second numeric value for same purposes 
* @return sum of two operands 
*/ 
public int add(int operand1, int operand2) {...} 

的Javadoc始終方法或變量或前級使用/接口

Answer 4

Javadoc style guide解釋了這些標籤的預期用途。 @param描述一個參數，@return描述返回值。 （還有其他幾個有用的標籤。）

請記住，Javadoc從您的代碼生成文檔，而不是只是從您的意見。該方法的簽名將出現在輸出中 - 因此，不告訴讀者他已經知道的東西。您的文檔的目的是提供未在簽名中表達的其他語義。那個數字參數是否被限制在一個特定的值範圍內？是否有任何特殊的返回值（如null）？記錄合同。

你問是否有太多的文件這樣的事情。就在這裏。當API參考文檔告訴讀者所有信息並且只有他需要知道正確使用接口時纔是最有用的。因此，要充分記錄合同，但不要說您的代碼如何實現此界面。如果它們直接影響你正在記錄的部分（例如，如果有人需要使用SomeFactory來獲得SomeThing的實例，你正在記錄的類），則鏈接到API的其他元素（例如其他類或接口）。

這並不是說你永遠不應該寫幾句話;有時界面很複雜，需要更多解釋。考慮該解釋是否屬於包概述，類或接口的頂級文檔或特定成員。如果你發現自己在幾個地方切割並粘貼解釋，這可能意味着你需要在更高的層次上解決它。