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

Question

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

boolean 集合.isEmpty()

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

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

Answer 1

来自 Oracle 的建议 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).