如何在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

---

我知道这是几年前的事情了，但是...查看官方的Java类可以帮助找到任何你需要的Javadoc格式。例如，可以查看HashMap Javadoc。 - Christophe Roussy

Answer 1

你可以在标准 Doclet 的文档注释规范中找到关于 JavaDoc 的大量信息，包括你正在寻找的

{@link 模块/包.类#成员 标签}

标签的相关示例如下：

例如，这是一个引用了 getComponentAt(int, int) 方法的注释：

使用 {@link #getComponentAt(int, int) getComponentAt} 方法。

如果所引用的方法在当前类中，则可以省略模块/包.类部分。

---

其他有关JavaDoc的有用链接包括：

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

- FrVaBe

Answer 2

从@link javadoc文档的链接部分可以得知，一般格式为：

例子

同一类中的方法：

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

不同类中的方法，可以是在相同的包中或者被导入：

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

不在同一 package 中的方法，且没有被导入：

/** 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发生变化时这种方式可能会很脆弱。

类型擦除和#成员

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

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

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

- Andy Thomas

---

等一下：我只想要方法名和链接，不需要类名。 - Jason S

啊，好的。上面链接中的第一个例子就阐述了这一点。 - Andy Thomas

+1 因为提供了一个我在 Oracle JavaDoc HowTo 页面中没有链接到的 Java 6 链接。我仍然无法使用 Oracle 的链接... (在我的答案中修正了 Java 6 的链接)。 - FrVaBe

@zasadnyy - 感谢您尝试添加关于泛型的重要注释。我很喜欢它，但是在其他人之前没有看到审查。我已将＃成员和泛型部分添加到上面的答案中。 - Andy Thomas

@JoseTepedino - 如果可能进行重构，那么标签就是有害的——而这些天，对于不与第三方共享的代码来说，重构非常容易。 - Andy Thomas

Answer 3

你可以使用@see来实现这一点：

示例：

interface View {
        /**
         * @return true: have read contact and call log permissions, else otherwise
         * @see #requestReadContactAndCallLogPermissions()
         */
        boolean haveReadContactAndCallLogPermissions();

        /**
         * if not have permissions, request to user for allow
         * @see #haveReadContactAndCallLogPermissions()
         */
        void requestReadContactAndCallLogPermissions();
    }

- vuhung3990

---

“如何使用@link标签链接到一个方法？” @link 标签可以嵌入段落中，正如OP所请求的那样。*@see*标签则不行。更多详情请参见此问题。 - Andy Thomas