JavaDoc 中@see 的用法？答案

【问题标题】：Usage of @see in JavaDoc?JavaDoc 中@see 的用法？
【发布时间】：2011-06-28 00:46:32
【问题描述】：

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

例如，如果MethodA 调用MethodB，那么我是否必须将@see 放入MethodB 的javadoc 并引用MethodA，因为这就是所谓的，还是我必须引用MethodB 来自 MethodA，因为它正在调用它。我在 Oracle 网站上阅读了有关 @see 的内容，在我看来它非常模糊，它说它的意思是“另见”，但并不是真正的意思！

【问题讨论】：

将@see 放入MethodB 的javadoc 并引用MethodA 因为这就是所谓的 --> 怎么可能知道所有的方法调用您的一种方法？即使这是可能的（比如一个只使用一次的私有方法）从被调用者到调用者的链接听起来至少很奇怪......
表示英文通常的意思：oxforddictionaries.com/us/definition/american_english/see（定义1.4）

标签： java methods javadoc

【解决方案1】：

是的，很模糊。

对于阅读您方法文档的读者来说，您应该使用它，同时查看其他方法可能会很有用。如果您的方法A 的文档说“像方法B 一样工作，但是...”，那么您肯定应该放置一个链接。 @see 的替代方法是内联 {@link ...} 标签：

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

当methodA调用methodB是一个实现细节并且与外部没有实际关系时，您不需要此处的链接。

【讨论】：

@see 也可用于链接到 @Deprecated 方法的替代方法。
@MauveRanger 由于@see 非常模糊，对于已弃用的东西，我发现做一些更明确的东西更有用，例如：@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

【解决方案2】：

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

【讨论】：

【解决方案3】：

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

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

Java SE 文档：@see

【讨论】：

不是我，但可能是因为我们有@inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…
@see 的 java 文档非常好。应该是第一个。
@vaxquis @inheritDoc 从另一个位置复制文档。我想描述细节而不是添加绒毛有其用途？
@Nielsvg 这个答案提到the overridden/implemented method could use a @see tag, referring to the base one. - 这正是@inheritDoc 的用途； IMO最好通过@inheritDoc逐字包含基类描述并根据需要补充它，而不是通过@see引用它 - 请参阅（原文如此！）stackoverflow.com/questions/11121600/…；许多开发人员（包括我）更喜欢将所有实现细节放在一个地方，而不是通过继承层次结构向上延伸的无休止的向上链接链。

【解决方案4】：

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

^{不同的 JavaDoc 链接类型}

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

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

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

查看以下结果：

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

最好的问候。

【讨论】：

+1 列出了在 javadoc 中通过示例使用链接的不同可能性。但请注意，其他 JavaDoc 渲染器的行为会有所不同！ 5. 例如，不适用于 IntelliJ。

【解决方案5】：

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

【讨论】：