我如何使用@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()

to:

/**
 * 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标签。


当前回答

一般格式,来自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不断发展的过程中,这可能很脆弱。

输入擦除和#成员

如果方法签名包含参数化类型,则在javadoc @link中使用擦除这些类型。例如:

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

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

其他回答

一般格式,来自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不断发展的过程中,这可能很脆弱。

输入擦除和#成员

如果方法签名包含参数化类型,则在javadoc @link中使用擦除这些类型。例如:

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

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

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

{@link module/package.class#成员标签}

(你要找的)标签。文档中对应的示例如下

例如,下面是引用getComponentAt(int, int)方法的注释: 使用{@link #getComponentAt(int, int) getComponentAt}方法。

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


关于JavaDoc的其他有用链接有:

JDK 17工具规格—javadoc命令 JavaDoc指南 如何为Javadoc工具写文档注释

你可以使用@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();
    }