Javadoc @see或{@link}?


184

有人可以告诉我javadoc @see和之间的区别{@link}吗?

或更确切地说,什么时候使用它们中的哪一个?

Answers:


213

官方指南上这是很清楚的。

功能上的差异是:

  • {@link} 是一个内联链接,可以放置在您喜欢的任何位置
  • @see 创建自己的部分

我认为,{@link}最好在描述中使用字面意义上的类,字段,构造函数或方法名称。用户将可以单击您所链接内容的javadoc。

@see在2种情况下使用注释:

  • 某些内容非常相关,但说明中未提及。
  • 我在描述中多次提到相同的事物,它被用来替代指向同一事物的多个链接。

我基于随机签出文档中标准库中各种各样内容的观点。


3
Javadoc确实警告@link相当密集,仅应在必要时使用。
托马斯

4
对于任何有兴趣的人,您都可以@linkOracle Javadoc指南中获得有关此信息的详细信息(包括上面注释中的有关警告)。
Ash Ryan Arnwine '16

48

@see在Javadocs中创建隔离线。{@link}用于嵌入文本中。

@see当它是一个相关实体时,我会使用它,但我不会在说明文字中引用它。在紧密耦合的情况下,我会在文本内使用链接,或者(我觉得)读者可能会从导航提示中受益,例如,您需要直接引用它。


3

还有一个参考(弃用部分)是相同的官方文档,而{@link}不是@see(自Java 1.2起)更喜欢:

对于Javadoc 1.2和更高版本,标准格式是使用@deprecated标签和嵌入​​式{@link}标签。这将在需要的位置在线创建链接。例如:

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

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.