Java 文档 - @return 和 @param答案

【问题标题】：Java Documentation - @return and @paramJava 文档 - @return 和 @param
【发布时间】：2014-04-17 16:37:32
【问题描述】：

我想知道如何使用@return 和@param 记录代码...？我有点猜测我会做类似的事情

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

之后我需要添加更多描述吗？另外，是不是文档太多了？

【问题讨论】：

标签： java documentation return param

【解决方案1】：

Javadoc style guide 解释了这些标签的预期用途。 @param 描述一个参数，@return 描述返回值。（还有其他几个有用的标签。）

请记住，Javadoc 从您的代码生成文档，而不是只是从您的 cmets。方法的签名将出现在输出中——因此，不要告诉读者他们已经知道的东西。您的文档的目的是提供签名中未表达的附加语义。该数字参数是否限制在特定的值范围内？是否有任何特殊的返回值（如 null）？记录合同。

您问是否存在过多的文档。就在这里。当 API 参考文档告诉读者所有并且只告诉他们正确使用接口所需知道的内容时，它是最有用的。所以完整地记录合同，但不要说你的代码是如何实现这个接口的。链接到 API 的其他元素（例如其他类或接口），如果它们直接与您正在记录的部分相关（例如，如果有人需要使用 SomeFactory 来获取 SomeThing 的实例，您的类）重新记录）。

这并不是说你永远不应该写超过几句话的东西。有时界面很复杂，需要更多解释。考虑该解释是否属于包概述、类或接口的顶级文档或特定成员。如果您发现自己在多个地方剪切和粘贴了解释，这可能表明您需要在更高的层次上解决它。

【讨论】：

【解决方案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 总是在方法或变量或类/接口之前使用

【讨论】：

【解决方案3】：

这是您所说的 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 文件。

之后我需要添加更多描述吗？

在它之前，事实上，作为一种约定。并且仅在您认为有必要时。

还有，是不是文档太多了？

是的。

【讨论】：

【解决方案4】：

为什么不从查找 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;
}

【讨论】：