java Javadoc@return标记注释是否需要复制？

Question

对于不改变实例状态的函数，该方法的javadoc注释通常与javaapi中@return标记的注释相同或非常相似

布尔集合。isEmpty（）

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

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

Answer 1

根据甲骨文的建议How to Write Doc Comments for Javadoc Tool：

@return (reference page)

Omit @return for methods that return void and for constructors; include it for all other methods, even if its content is entirely redundant with the method description. Having an explicit @return tag makes it easier for someone to find the return value quickly. Whenever possible, supply return values for special cases (such as specifying the value returned when an out-of-bounds argument is supplied).

Answer 2

如果你（和我一样）真的不喜欢违反DRY，那么这是javadoc参考文件中最重要的一行：

It is possible to have a comment with only a tag section and no main description.

（@seehttp://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 );

这是（在相互了解一点之后）在源代码中更具可读性和更好的可维护性，因为它的形式较长

Answer 3

由于Java 16，建议的解决方案是使用新引入的标准Doclet inline ^{} tag：

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

这将生成一个“返回描述”summary，后面跟着你在它后面写的内容，另外使用描述来描述返回值：

请注意，“返回…”句子已经以句号结尾；你不应该在{@return }后面添加一个显式的

Answer 4

使用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