java - Javadoc @return 标记注释重复是否必要？

Question

对于不改变实例状态的函数，该方法的 javadoc 注释通常与 Java-API 中 @return-tag 的注释相同或非常相似。

布尔集合.isEmpty()

• 如果此集合不包含任何元素，则返回 true。
• 返回：如果此集合不包含任何元素，则返回 true

现在我正在为许多简单的方法（如 getExpression()）编写 javadoc，但我遇到了同样的问题。我应该像在 API 中那样做还是忽略它？

Answer 1

来自 Oracle 的建议How to Write Doc Comments for Javadoc Tool：

@return（参考页）

对于返回 void 的方法和构造函数，省略 @return；将它包含在所有其他方法中，即使它的内容与方法描述完全多余。有一个明确的@return 标签可以让人们更容易快速找到返回值。只要有可能，为特殊情况提供返回值（例如在提供越界参数时指定返回值）。

Answer 2

如果您（像我一样）真的不喜欢违反 DRY，那么这是 javadoc ref 中最重要的几行之一：

可以有一个只有标签部分而没有主要描述的评论。

（@参见http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#tagsection）

因此，编写 javadoc 的简单方法是完全有效的（并且有效），例如：

/**
* @return the name of the object
*/
public String getName();

所以你甚至可以写这样的东西：

/**
* @return the n-th element of the object
*
* @param n index of element to get
*/
public String get( int n );

哪个（在彼此了解一点之后）在源代码中更具可读性，并且作为违反 DRY 的较长形式更易于维护。

Answer 3

对于javadoc16，您可以使用新的组合{@return ...}标签，以“避免在简单情况下重复返回信息”。

/**
 * {@return the name of the object}
 */
public String getName();

等效于（仍然支持的）样式：

/**
 * Returns the name of the object.
 *
 * @return the name of the object
 */
public String getName();

在https://bugs.openjdk.java.net/browse/JDK-8075778找到更多详细信息

Answer 4

从 Java 16 开始，推荐的解决方案是使用标准 Doclet新引入的内联标记：{@return description}

/**
 * {@return the name} {@code null} if unknown.
 */
public String getName() {
    ...
}

这将生成一个“退货说明”。总结，后面跟着你写的任何东西，另外使用描述作为返回值的描述：

请注意，“Returns ...”语句已经以句点结尾；你不应该在{@return }.