如何在javadoc中引用方法?


863

如何使用@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正确设置标签格式。


22
我知道这是几年前的事,但是...查看官方Java类可以帮助您找到所需的任何形式的Javadoc格式。例如,查看HashMap Javadoc。
Christophe Roussy 2014年

Answers:


1120

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

{@link package.class#member标签}

标签(您要查找的)。文档中的相应示例如下

例如,以下注释引用了getComponentAt(int,int)方法:

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

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


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


743

来自javadoc文档@link部分的常规格式为:

{@link package.class#member标签}

例子

同一类中的方法:

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

等待:我只想要带有链接的方法名称,我也不想要类名称。
詹森·S

啊好吧。上面链接中的第一个示例说明了这一点。
安迪·托马斯

1
+1,用于提供我没有从Oracle JavaDoc HowTo页面链接到的Java 6链接。我仍然无法与oracle链接相处...(答案中固定为Java 6的链接)。
FrVaBe


@PaŭloEbermann谢谢!将来将尝试使用“文档”页面作为切入点。
FrVaBe

16

您可以@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();
    }

4
OP:“如何使用@link标记链接到方法?” 根据OP的要求,可以在段落中内联使用@link标记。该@see标签不能。看到这个问题的更多细节。
安迪·托马斯
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.