java - @see 和 @inheritDoc 之间的区别的详细信息

Question

我看过JavaDoc reference ，虽然我了解 @see (各种链接)和 {@inheritDoc} (父类(super class) JavaDoc 注释的导出)之间的基本区别，但我需要澄清事情的实际实现方式。

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

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

如果我需要生成 JavaDoc，我应该把它留在那里，将 @see 替换为 {@inheritDoc}，或者将其转为 善意 像这样的 JavaDoc:

/**
 * {@inheritDoc}
 */

当我这样做时，我还应该保留 class#method 标志吗？

Answer 1

首先，您应该删除原始的 eclipse 模板，因为它只是嘈杂的垃圾。要么放入有意义的文档，要么根本不放入任何东西。但是，使用 IDE 模板对显而易见的内容进行无用的重述只会使代码变得困惑。

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

最后，如果您要覆盖，那么您应该使用 @inheritDoc (假设您想 add 到原始文档中，正如@seh 在评论中指出的那样，如果您只是想复制原始文档，那么你不需要任何东西)。 @see 应该只真正用于引用其他相关的方法。