在JavaDoc中使用@see？

Question

在处理JavaDocs时何时使用@see？它的用途是什么？

例如，如果MethodA调用MethodB，那么我是否必须将@see放入MethodB的javadoc并引用MethodA，因为这就是所谓的，或者我必须在MethodB中引用MethodA，因为它正在调用它。我已经在Oracle网站上阅读了关于@see的内容，在我看来它非常模糊，它说这意味着“也看到了”但不是真的意味着什么！

Answer 1

是的，它很模糊。

对于方法文档的读者，无论何时阅读其他方法，都应该使用它。如果你的方法A的文档说“像方法B一样但是......”，那么你肯定应该建立一个链接。 @see的替代方案是内联{@link ...}标记：

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

当methodA调用methodB的事实是一个实现细节而且外部没有真正的关系时，你不需要这里的链接。

Answer 2

@see对于API中相关方法/类的信息非常有用。它将生成指向文档中引用的方法/代码的链接。当有相关代码可能有助于用户理解如何使用API​​时使用它。

Answer 3

@see可能有用的情况的一个很好的例子是实现或覆盖接口/抽象类方法。该声明将有javadoc部分详细说明该方法，并且重写/实现的方法可以使用@see标记，引用基础标记。

相关问题： Writing proper javadoc with @see?

Java SE文档：@see

Answer 4

@see 标签与 @link 标签略有不同，
在某些方面受到限制，而在其他方面则更加灵活。
以下示例来自 Eclipse：

^{不同的 JavaDoc 链接类型}

1. 显示成员名称便于学习，可重构；通过重构重命名时名称将更新
2. 可重构和可定制；显示的是您的文字而不是会员名
3. 显示名称，可重构
4. 可重构、可定制
5. 一个相当平庸的组合：

• 可重构、可定制，并留在另见部分
• 在 Eclipse 悬停中很好地显示
• 在生成时显示链接标签及其格式?
• 当使用多个 @see 项时，说明中的逗号会使输出变得混乱

6. 完全非法；导致生成器出现意外内容和非法字符错误

查看以下结果：

^{不同链接类型的JavaDoc生成结果}

最好的问候。

Answer 5

我使用@see来注释接口实现类的方法，其中已经在接口的javadoc中提供了该方法的描述。当我们这样做时，我注意到Eclipse提取了界面的文档，即使我在代码完成期间查找实现引用的方法