Java 文档 - @return 和 @param

Java Documentation - @return and @param

提问by allyhalcyon

I'm wondering how to document code with @return and @param ...? I'm sort of guessing that I would do something like

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

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

Would I have to put more descriptions afterwards? Also, is there something as too much documentation?

之后我是否需要添加更多描述？另外，是否有太多文档？

回答by Tristan

Why not start by looking up what JavaDocs are?

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

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

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

An example of how they are used is like this.

它们是如何使用的一个例子是这样的。

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

回答by fge

This is Javadoc you are talking about:

这是您正在谈论的 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
}

The javadoc tool (and targets which use this tool in various build systems such as gradle and maven) will generate HTML files from that.

javadoc 工具（以及在各种构建系统（如 gradle 和 maven）中使用此工具的目标）将从中生成 HTML 文件。

Would I have to put more descriptions afterwards?

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

Before it, in fact, as a convention. And only if you deem it necessary.

在它之前，其实作为约定俗成的。并且仅当您认为有必要时。

Also, is there something as too much documentation?

另外，是否有太多文档？

Yes.

是的。

回答by Anver

Those things are javadoc tags. Full reference of how to use they you can find here: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

那些东西是 javadoc 标签。您可以在此处找到有关如何使用它们的完整参考：http: //www.oracle.com/technetwork/java/javase/documentation/index-137868.html

But basic example for those two you have mentioned above will look like this:

但是上面提到的那两个的基本示例如下所示：

/**
 * 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 are always used before method or variable or class / interface

Javadocs 总是在方法或变量或类/接口之前使用

回答by Monica Cellio

The Javadoc style guideexplains the intended uses of these tags. @paramdescribes a parameter and @returndescribes the return value. (There are several other useful tags.)

该的Javadoc风格指南解释了这些变量的预期用途。 @param描述一个参数并@return描述返回值。（还有其他几个有用的标签。）

Remember that Javadoc generates documentation from your code, not justfrom your comments. The signature of the method will appear in the output -- therefore, don't tell the readers stuff they already know. The purpose of your documentation is to supply the additional semantics not expressed in the signature. Is that numeric parameter constrained to a particular range of values? Are there any special return values (like null)? Document the contract.

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

You ask if there is such a thing as too much documentation. Yes, there is. API reference documentation is most useful when it tells the readers all and only what they need to know to properly use the interface. So fully document the contract, but say nothing abut how your code implements this interface. Link to other elements of the API (such as other classes or interfaces) if they directly bear on the part you're documenting (for example if somebody needs to use SomeFactoryto obtain an instance of SomeThing, the class you're documenting).

你问是否有太多文档这样的事情。就在这里。当 API 参考文档告诉读者正确使用接口所需的全部信息时，它是最有用的。所以完整地记录合同，但只说你的代码如何实现这个接口。链接到 API 的其他元素（例如其他类或接口），如果它们直接涉及您正在记录的部分（例如，如果有人需要使用SomeFactory来获取SomeThing您正在记录的类的实例）。

This isn't to say that you should never write anything longer than a few sentences; sometimes an interface is complex and requires more explanation. Consider whether that explanation belongs in a package overview, the top-level documentation of a class or interface, or a specific member. If you find yourself cutting and pasting an explanation in several places, that may be a sign that you need to address it at a higher level instead.

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