Question

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

的事情

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

之后我是否需要提供更多说明？还有，有太多的文件吗？

Answer 1

Javadoc style guide解释了这些标签的预期用途。 @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文件。

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

之前，事实上，作为一种惯例。只有你认为有必要。

另外，是否存在太多文档？

是

Java文档 - @return和@param

4 个答案: