[英]How to reference a method in javadoc?
如何使用@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
标签。
您可以在标准 Doclet的文档注释规范中找到有关 JavaDoc 的许多信息,包括有关
标签(您正在寻找)。 文档中的相应示例如下
例如,这里是引用 getComponentAt(int, int) 方法的注释:
Use the {@link #getComponentAt(int, int) getComponentAt} method.
如果引用的方法在当前类中,则可以省略package.class
部分。
关于 JavaDoc 的其他有用链接是:
来自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() { ... }
你可以使用@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();
}
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.