如何在 javadoc 中引用一个方法？

Question

如何使用 @link 标签链接到方法？

我想改变：

 /**
 * Returns the Baz object owned by the Bar object owned by Foo owned by this.
 * A convenience method, equivalent to getFoo().getBar().getBaz()
 * @return baz
 */
public Baz fooBarBaz()

至：

 /**
 * Returns the Baz object owned by the Bar object owned by Foo owned by this.
 * A convenience method, equivalent to {@link getFoo()}.{@link getBar()}.{@link getBaz()}
 * @return baz
 */
public Baz fooBarBaz()

但我不知道如何正确格式化 @link 标签。

原文由 Jason S 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

您会 在标准 Doclet 的文档注释规范中 找到很多关于 JavaDoc 的信息，包括关于

{@link module/package.class#member label}

标签（您正在寻找的）。文档中对应的例子如下

例如，这里有一条引用 getComponentAt(int, int) 方法的注释：

Use the {@link #getComponentAt(int, int) getComponentAt} method.

module/package.class 如果引用的方法在当前类中，则可以省略部分。

---

关于 JavaDoc 的其他有用链接是：

• JDK 17 工具规范 - javadoc 命令
• 文档指南
• 如何为 Javadoc 工具编写文档注释

原文由 FrVaBe 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 2

来自 javadoc 文档 @link 部分的 一般格式是：

例子

同一个类中的方法：

 /** See also {@link #myMethod(String)}. */
void foo() { ... }

不同类中的方法， 在同一个包中或导入：

 /** See also {@link MyOtherClass#myMethod(String)}. */
void foo() { ... }

不同包 中的方法，未导入：

 /** See also {@link com.mypackage.YetAnotherClass#myMethod(String)}. */
void foo() { ... }

链接到方法的标签，以纯文本 而不是代码字体：

 /** See also this {@linkplain #myMethod(String) implementation}. */
void foo() { ... }

一系列方法调用， 如您的问题。我们必须为指向此类外部方法的链接指定标签，否则我们会得到 getFoo().Foo.getBar().Bar.getBaz() 。但这些标签在重构过程中可能很脆弱——请参阅下面的“标签”。

 /**
 * A convenience method, equivalent to
 * {@link #getFoo()}.{@link Foo#getBar() getBar()}.{@link Bar#getBaz() getBaz()}.
 * @return baz
 */
public Baz fooBarBaz()

标签

自动重构可能不会影响标签。 这包括重命名方法、类或包；并更改方法签名。

因此， 仅 当您需要与默认文本不同的文本时才提供标签。

例如，您可以将人类语言链接到代码：

 /** You can also {@linkplain #getFoo() get the current foo}. */
void setFoo( Foo foo ) { ... }

或者您可以从代码示例链接到与默认文本不同的文本，如上文“方法调用链”下所示。但是，随着 API 的发展，这可能很脆弱。

键入擦除和#member

如果方法签名包含参数化类型，请在 javadoc @link 中使用这些类型的擦除。例如：

 int bar( Collection<Integer> receiver ) { ... }

/** See also {@link #bar(Collection)}. */
void foo() { ... }

原文由 Andy Thomas 发布，翻译遵循 CC BY-SA 4.0 许可协议