在JavaDoc中使用@see？

Question

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

例如,如果MethodA呼叫MethodB然后做我必须把@see中MethodB的javadoc和引用MethodA,因为这就是所谓呢,还是我已经把一个引用MethodB从MethodA,因为它调用它.我已经阅读了@seeOracle网站上的内容,在我看来它非常模糊,它说它意味着"也看到"但不是真的意味着什么!

Answer 1

是的,它很模糊.

无论何时对于方法文档的读者,您都应该使用它,同时查看其他方法也很有用.如果你的方法A的文档说"像方法B一样但是......",那么你肯定应该建立一个链接.@see内联{@link ...}标记的替代方法是:

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

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

Answer 2

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

Answer 3

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

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

Java SE文档: @see

Answer 4

该@see标签是不是有点不同的@link标签，
限制在某些方面，而在其他更灵活。
以下示例来自 Eclipse：

^{不同的 JavaDoc 链接类型}

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

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

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

查看以下结果：

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

此致。