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

为什么不首先查找 JavaDoc 是什么？

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;
}