Javadoc @return标签评论重复是否必要？

Question

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

boolean Collection.isEmpty（）

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

现在我正在为许多简单的方法编写javadoc，比如getExpression（），我遇到同样的问题。我应该像在API中那样做还是把它留下来？

Answer 1

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

  

@return（参考页面）

     

忽略@return表示返回void和构造函数的方法; 将其包含在所有其他方法中，即使其内容完全是   多余的方法说明。有一个明确的@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

使用 javadoc 16，您可以使用新的组合 {@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 新引入的 inline {@return description} tag：

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

这将生成一个“退货描述”。摘要，后面跟着你写的任何内容，另外使用描述作为返回值的描述：

请注意，“Returns ...”句子已经以句点结尾；你不应该在 {@return } 后面添加一个明确的。