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

Question

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

boolean Collection.isEmpty()

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

Answer 1

@return(参考页)

忽略@return表示返回void和构造函数的方法; 将其包含在所有其他方法中,即使其内容与方法描述完全不同.使用显式的@return标记可以让人们更容易快速找到返回值.尽可能为特殊情况提供返回值(例如指定提供越界参数时返回的值).

Answer 2

如果你(像我一样)真的不喜欢违反DRY,那么这是javadoc ref中最重要的一行:

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

因此,编写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的更长形式更易于维护.

出于某种原因,Google风格指南(https://google.github.io/styleguide/javaguide.html#s7.2-summary-fragment,第7.2点)将此称为"常见错误",并建议省略@return注释完全只是使用描述.这似乎与Oracle的建议不一致. (3认同)
就是说，他们不使用仅标记的Javadoc似乎很有效：例如，如果您查看https://docs.oracle.com/javase/7/docs/api/java/util/ArrayList.html，，则开头的方法列表仅包含正文，如果注释仅包含标签，则正文将为空。 (2认同)

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();

Answer 4

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

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

这将生成“退货说明”。摘要，后跟您在其后面编写的任何内容，并另外使用描述作为返回值的描述：

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