我想知道如何使用@return 和@param 来记录代码...？我猜我会做类似的事情
@return(whatever the method is returning)
@param(parameters that the method is taking in)
之后我是否需要添加更多描述？另外，是否有太多文档？
最佳答案
Javadoc style guide解释了这些标签的预期用途。 @param 描述了一个参数，@return 描述了返回值。 (还有其他几个有用的标签。)
请记住，Javadoc 根据您的代码生成文档，而只是根据您的注释。该方法的签名将出现在输出中——因此，不要告诉读者他们已经知道的东西。您的文档的目的是提供签名中未表达的附加语义。该数字参数是否受限于特定的值范围？是否有任何特殊的返回值(如 null)？记录契约(Contract)。
你问是否有太多文档这样的事情。就在这里。当 API 引用文档告诉读者正确使用接口(interface)所需了解的所有内容时，它是最有用的。所以完整地记录契约(Contract)，但只说你的代码如何实现这个接口(interface)。链接到 API 的其他元素(例如其他类或接口(interface))，如果它们直接影响您正在记录的部分(例如，如果有人需要使用 SomeFactory 来获取 的实例SomeThing，您正在记录的类)。
这并不是说您不应该写任何超过几句话的东西；有时界面很复杂，需要更多解释。考虑该解释是否属于包概述、类或接口(interface)的顶级文档或特定成员。如果您发现自己在多个地方剪切和粘贴解释，则可能表明您需要在更高级别解决它。
关于Java 文档 - @return 和 @param，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/22370244/