JavaDoc中@see的用法？

110

什么时候使用@see与JavaDoc中处理时？它的用途是什么？

例如，如果MethodA呼叫MethodB然后做我必须把@see中MethodB的javadoc和引用MethodA，因为这就是所谓呢，还是我已经把一个引用MethodB从MethodA，因为它调用它。我已经阅读了@seeOracle网站上的内容，在我看来似乎非常模糊，它表示“请参见”，但实际上并不意味着！

java methods javadoc

— 杰夫
source

4

摆@see在MethodB的javadoc和参考MethodA，因为那是什么把它称为 - >如何将是有史以来可能知道哪些调用你的方法之一，所有的方法？即使这是可能的（例如，仅使用一次私有方法）从被叫方链接到主叫方，听起来至少也很奇怪……

— Mr_and_Mrs_D 2013年

1

这意味着它通常是指英文：oxforddictionaries.com/us/definition/american_english/see（定义1.4）

— stackexchanger

119

是的，这很模糊。

每当对方法文档的读者来说，都应该使用它，同时查看其他方法可能会很有用。如果您的methodA文档说“工作方式与methodB相似，但...”，那么您当然应该放置一个链接。替代方法@see是内联{@link ...}标签：

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

当methodA调用methodB的事实是一个实现细节，并且与外界没有真正的联系时，您无需在此处链接。

— 帕洛·埃伯曼
source

13

@see对于链接到@Deprecated方法的替代方法也很有用。

— 莫夫·兰杰

1

@MauveRanger由于@see含糊不清，对于不推荐使用的东西，我发现做一些更明确的事情会更有用，例如：@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Christopher

10

@see可用于获取有关API中相关方法/类的信息。它将在文档中提供指向所引用方法/代码的链接。有相关代码可以帮助用户了解如何使用API时，请使用它。

— 罗伯·道森
source

9

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

相关问题：使用@see编写适当的javadoc？

Java SE文档： @see

— 原子之父
source

2

不是我，但这可能是因为我们有@ inheritDocdocs.oracle.com

1

@see的java文档非常好。应该是第一位。

— dok

2

@vaxquis @inheritDoc从另一个位置复制文档。我想象描述细节而不是添加绒毛有其用处吗？

— Nielsvh'2

@Nielsvg这个答案提到了the overridden/implemented method could use a @see tag, referring to the base one.-这正是@inheritDoc目的。IMO最好通过逐字方式包含基类描述@inheritDoc 并根据需要对其进行补充，而不是通过@see- 来引用它-参见（sic！）stackoverflow.com/questions/11121600/… ; 许多开发人员（包括我在内）更喜欢将所有实现细节都放在一个位置，而不是无休止的向上链接链通过继承层次结构向上引导。

2

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

— 马鲁蒂
source