JavaDoc 中 @see 的用法？

Question

处理 JavaDocs 时什么时候使用

@see

？它的用途是什么？

例如，如果

MethodA

调用

MethodB

那么我是否必须将

@see

放入

MethodB

的 javadoc 并引用

MethodA

，因为这就是调用它的原因，或者我是否必须引用

MethodB 

来自

MethodA

因为它正在调用它。我在 Oracle 网站上读过有关

@see

的内容，在我看来，它非常模糊，它说它的意思是“另请参阅”，但实际上并不是这意味着什么！

Answer 1

是的，这很模糊。

只要对您的方法文档的读者查看其他方法可能有用，您就应该使用它。如果你的 methodA 的文档说“与 methodB 类似，但是......”，那么你肯定应该添加一个链接。

@see

的替代方案是内联

{@link ...}

标签：

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

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

Answer 2

@see

标签与

@link

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

^{不同的 JavaDoc 链接类型}

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

• 可重构、可定制，并保留在另请参阅部分
• 在 Eclipse 悬停中显示良好
• 生成时显示链接标签及其格式😞
• 使用多个

  @see

  项目时，描述中的逗号会使输出混乱

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

查看下面的结果：

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

致以诚挚的问候。

Answer 3

@see

有用的情况的一个很好的例子是实现或重写接口/抽象类方法。声明将有

javadoc

部分详细说明该方法，并且重写/实现的方法可以使用

@see

标签，引用基础标签。

相关问题： 用@see编写正确的javadoc？

Java SE 文档：

@see

Answer 4

@see 对于 API 中相关方法/类的信息很有用。它将生成文档中引用的方法/代码的链接。当有相关代码可以帮助用户了解如何使用 API 时使用它。

Answer 5

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