是否应该将 Javadoc 注释添加到实现中？

Question

在接口中添加 Javadoc 注释并在实现中添加非 Javadoc 注释是正确的做法吗？

当您自动生成注释时，大多数 IDE 会为实现生成非 JavaDoc 注释。具体方法不应该有描述吗？

原文由 Vaishak Suresh 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

对于仅实现（而非覆盖）的方法，当然，为什么不呢，特别是如果它们是公共的。

如果你有一个压倒一切的情况并且你打算复制任何文本，那么绝对不会。复制是造成差异的必经之路。因此，用户会对您的方法有不同的理解，这取决于他们检查的是超类型还是子类型中的方法。使用 @inheritDoc 或不提供文档 - IDE 将在其 Javadoc 视图中使用最少的可用文本。

顺便说一句，如果您的覆盖版本向超类型的文档中添加内容，您可能会遇到麻烦。我在攻读博士学位期间研究了这个问题，发现如果人们通过超类型调用，通常他们永远不会意识到覆盖版本中的额外信息。

解决这个问题是我构建的原型工具的主要特性之一——每当您调用一个方法时，您都会得到一个指示，指示它的目标或任何潜在的覆盖目标是否包含重要信息（例如，冲突行为）。例如，在地图上调用 put 时，系统会提醒您，如果您的实现是 TreeMap，则您的元素需要具有可比性。

原文由 Uri 发布，翻译遵循 CC BY-SA 3.0 许可协议

Answer 2

实现和接口都应该有 javadoc。借助一些工具，您可以使用@inheritDoc 关键字来继承接口的文档。

 /**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }

原文由 Sjoerd 发布，翻译遵循 CC BY-SA 3.0 许可协议