一、简介
在本教程中,我们将讨论如何在Javadoc 注释中引用 Java 方法。此外,我们还将讨论如何引用不同类和包中的方法。
2. @link 标签
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_member 、 label 和右大括号之间没有空格限制。
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 上找到。