Javadoc @see 还是 {@link}？

Question

有人能告诉我 javadoc @see 和 {@link} 之间的区别吗？

或者更确切地说，什么时候使用它们中的哪一个？

Answer 1

上面的official guidelines很清楚。

功能上的区别是：

• {@link} 是一个内联链接，可以放在任何你喜欢的地方
• @see 创建自己的部分

在我看来，{@link} 最好在您在描述中使用类、字段、构造函数或方法名称时使用。用户将能够点击进入您所链接内容的 javadoc。

我在2种情况下使用@see注解：

• 有些东西非常相关，但在描述中没有提到。
• 我在描述中多次提到同一个东西，它被用来代替多个指向同一个东西的链接。

我的这一观点是基于随机检查标准库中各种内容的文档。

Answer 2

@see 在 Javadocs 中创建一个独立的行。 {@link} 用于嵌入文本。

当它是一个相关实体时，我使用@see，但我没有在说明性文本中提及它。当存在紧密耦合时，我会在文本中使用链接，或者（我觉得）读者可能会从导航提示中受益，例如，您需要直接引用它。

Answer 3

还有另一个参考（弃用部分）相同的 official docs 更喜欢 {@link} 而不是 @see（从 Java 1.2 开始）：

对于 Javadoc 1.2 及更高版本，标准格式是使用 @deprecated 标签和内联 {@link} 标签。这将创建内联链接，其中 你想要它。例如：

对于 Javadoc 1.1，标准格式是创建一对 @deprecated 和 @see 标记。例如：

Answer 4

@see 标签与@link 标签有点不同，
在某些方面受到限制，在其他方面更灵活：

^{不同的 JavaDoc 链接类型}

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

• 可重构、可自定义并保留在另请参阅部分
• 在 Eclipse 悬停中很好地显示
• 生成时显示链接标签及其格式 ?
• 当使用多个 @see 项目时，描述中的逗号会使输出混乱

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

查看以下结果：

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

最好的问候。