@see和@inheritDoc之间的区别细节

Question

我已经查阅了JavaDoc参考文档，虽然我理解@see（各种链接）和{@inheritDoc}（导出超类的JavaDoc注释）之间的基本区别，但我需要澄清实际实现方式。

在Eclipse IDE中，当我为继承方法（从接口或toString()覆盖等）选择“生成元素注释”时，它会创建以下注释：

/* (non-Javadoc)
 * @see SomeClass#someMethod()
 */

如果我需要生成JavaDoc，我应该只保留它吗，还是用{@inheritDoc}替换@see，或者将其转换为真正的JavaDoc文档，如下所示：

/**
 * {@inheritDoc}
 */

当我这样做时，我是否仍应保留class＃method标记？

- theUg

Answer 1

首先，你应该删除原始的Eclipse模板，因为它只是嘈杂的垃圾。要么放置有意义的文档，要么不放置任何东西。但是使用IDE模板毫无意义地重申显而易见的内容只会使代码混乱。

其次，如果你需要生成javadoc，那么你必须让注释以/**开头。否则，这就不是javadoc。

最后，如果你正在覆盖一个方法，那么你应该使用 @inheritDoc（假设你想在原始文档中添加内容）。正如@seh在评论中所指出的那样，如果你只想复制原始文档，则不需要添加任何内容。 @see 应该仅用于引用其他相关方法。

- jtahlborn

---

仅当您打算添加到原始超类文档时，才应使用@inheritDoc。如果您仅想将其复制一份，Javadoc已经可以实现此功能，并指出超类文档适用于子类的重写方法，因为子类未提供任何额外的文档。 - seh

我使用了 @inheritDoc 生成文档，与未使用它的文档相比并没有看到明显差异。即使没有 @inheritDoc，我也能看到派生类的 Javadoc 被附加到了基类中。 - randominstanceOfLivingThing

我来这里是因为checkstyle抱怨“方法似乎不是为扩展而设计的”。一个好主意可能是使用@inheritDoc，然后添加一些实现特定的文档，例如它如何实现/覆盖父方法，特别是为什么以这种方式执行。 - Benjamin Marwell