Java文檔 - @return和@param

Question

我想知道如何使用@return和@param來記錄代碼......？ 我有點猜測我會做類似的事情

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

我之后是否需要提供更多說明？ 還有，有太多的文件嗎？

Answer 1

Javadoc樣式指南解釋了這些標簽的預期用途。 @param描述了一個參數，@ return描述了返回值。 （還有其他一些有用的標簽。）

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

你問是否存在太多文檔這樣的事情。 就在這里。 API參考文檔在告訴讀者所有內容以及正確使用該界面時他需要了解的內容時非常有用。 因此，請完整記錄合同，但不要說明代碼如何實現此接口。 鏈接到API的其他元素（例如其他類或接口），如果它們直接承載您正在記錄的部分（例如，如果有人需要使用SomeFactory來獲取SomeThing的實例，那么您正在記錄的類）。

這並不是說你永遠不應該寫幾句話; 有時界面很復雜，需要更多解釋。 考慮該解釋是否屬於包概述，類或接口的頂級文檔或特定成員。 如果您發現自己在幾個地方剪切並粘貼解釋，那么這可能表示您需要在更高級別處理它。

Answer 2

那些東西是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) {...}

Javadocs總是在方法或變量或類/接口之前使用

Answer 3

為什么不從查找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 4

這是你在談論的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文件。

我之后是否需要提供更多說明？

事實上，在它之前，作為一種慣例。 只有你認為有必要。

還有，有太多的文件嗎？

是。