如何在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正确格式化标签.

Answer 1

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

{@link package.class#member label}

标签(您正在寻找).文档中的相应示例如下

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

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

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

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

• JavaDoc工具参考
• JavaDoc指南
• 如何为Javadoc工具编写Doc注释

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() { ... }

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();
    }