一、简介

在本教程中,我们将讨论如何在Javadoc 注释中引用 Java 方法。此外,我们还将讨论如何引用不同类和包中的方法。

Javadoc 提供了 @link 内联标记来引用 Java 类中的成员 。我们可以认为 @link 标签类似于HTML中的锚标签,用于通过超链接将一个页面链接到另一个页面。

让我们看一下使用 @link 标记在 Javadoc 注释中引用方法的语法:

{@link path_to_member label}

与锚标记类似, path_to_member 是目的地, 标签 是显示文本。

标签 是可选的,但引用方法时需要 path_to_member 。但是,最好始终使用标签名称以避免复杂的参考链接。根据我们引用的方法是否位于同一个类中, path_to_member 的语法有所不同。

应该注意的是, 左大括号 {@link 之间不能有空格。 如果它们之间有空格,Javadoc 工具将无法正确生成引用。但是, path_to_memberlabel 和右大括号之间没有空格限制。

3. 引用同一个类中的方法

引用方法的最简单方法是从同一个类中引用:

{@link #methodName() LabelName}

假设我们正在记录一个方法,并且想要引用同一类中的另一个方法:

/**
 * Also, check the {@link #move() Move} method for more movement details.
 */
public void walk() {
}

public void move() {
}

在这种情况下, walk() 方法引用同一类中的 move() 实例方法。

如果被引用的方法有参数, 那么每当我们想要引用重载或参数化方法时,都必须相应地指定其参数的类型

考虑以下引用重载方法的示例:

/**
 * Check this {@link #move(String) Move} method for direction-oriented movement.
 */
public void move() {

}

public void move(String direction) {

}

move() 方法是指一种采用一个 String 参数的重载方法。

4. 引用另一个类中的方法

要引用另一个类中的方法,我们将使用类名称,后跟主题标签,然后是方法名称:

{@link ClassName#methodName() LabelName}

除了在 # 符号之前提及类名之外,语法类似于引用同一类中的方法。

现在,让我们考虑引用另一个类中的方法的示例:

/**
 * Additionally, check this {@link Animal#run(String) Run} method for direction based run.
 */
public void run() {

}

引用的方法位于 Animal 类中,该类位于 同一个包中

public void run(String direction) {

}

如果我们想引用另一个包中的方法,我们有两个选择。一种方法是 直接指定包和类名

/**
 * Also consider checking {@link com.baeldung.sealed.classes.Vehicle#Vehicle() Vehicle} 
 * constructor to initialize vehicle object.
 */
public void goToWork() {

}

在本例中,已经提到了 Vehicle 类以及完整的包名称,以引用 Vehicle() 方法。

此外,我们可以 导入包并单独提及类名

import com.baeldung.sealed.records.Car;

/**
 * Have a look at {@link Car#getNumberOfSeats() SeatsAvailability} 
 * method for checking the available seats needed for driving.
 */
public void drive() {

}

这里,驻留在另一个包中的 Car 类已被导入。因此, @link 只需要包含类名和方法。

我们可以选择这两种方式之一来引用不同包中的方法。如果是一次性使用该包,那么我们可以采用第一种方式,否则,如果有多个依赖,我们应该选择第二种方式。

5.*@linkplain* 标签

我们已经在注释中看到了用于引用方法的 @link Javadoc 标记。 Javadoc 提供了另一个名为 @linkplain 的标签,用于在注释中引用方法,该标签与 @link 标签类似。主要区别在于,在生成文档时, @link 以等宽格式文本生成标签值,而 @linkplain 以标准格式(如纯文本)生成标签值

六,结论

在本文中,我们讨论了如何在 Javadoc 注释中引用方法,并且还探讨了在其他类和包中引用方法。最后,我们检查了 @link@linkplain 标签之间的区别。

与往常一样,本文的代码示例可以在 GitHub 上找到。