Referencing a Method in Javadoc Comments – 在Javadoc注释中引用一个方法

1. Introduction

1.绪论

In this tutorial, we’ll discuss how to reference Java methods in Javadoc comments. Additionally, we’ll address how to reference methods in different classes and packages.

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

2. The @link Tag

2.@link标签

Javadoc provides the @link inline tag for referencing the members in the Java classes. We can think of the @link tag as similar to the anchor tag in HTML, which is used to link one page to another via hyperlinks.

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

Let’s look at the syntax for using the @link tag to reference methods in a Javadoc comment:

让我们看看在Javadoc注释中使用@link标签来引用方法的语法。

{@link path_to_member label}

Similar to the anchor tag, the path_to_member is the destination, and the label is the display text.

与锚标签类似，path_to_member是目的地，而label是显示文本。

The label is optional, but path_to_member is required to reference a method. However, it’s a good practice to always use the label name to avoid complex reference links. The syntax for the path_to_member differs based on whether the method we’re referencing resides in the same class or not.

label是可选的，但是path_to_member在引用方法时是必须的。然而，为了避免复杂的引用链接，总是使用标签名是一个好的做法。path_to_member的语法根据我们所引用的方法是否在同一个类中而有所不同。

It should be noted that there must be no spaces between the opening curly bracket { and @link. The Javadoc tool won’t generate the reference properly if there’s a space between them. However, there is no space restriction between path_to_member, label, and the closing curly bracket.

需要注意的是，开头的大括号{和@link之间不能有空格。如果它们之间有空格，Javadoc工具将不能正常生成引用。然而，在path_to_member、label和结尾的大括号之间没有空格的限制。

3. Referencing a Method in the Same Class

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

The simplest way to reference a method is from within the same class:

引用一个方法的最简单方法是在同一个类中。

{@link #methodName() LabelName}

Let’s say we are documenting a method, and we want to reference another method from within the same class:

假设我们正在记录一个方法，并且我们想从同一个类中引用另一个方法。

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

public void move() {
}

In this case, the walk() method references the move() instance method within the same class.

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

If the method being referenced has arguments, we must specify the type of its arguments accordingly whenever we want to refer to an overloaded or parameterized method.

如果被引用的方法有参数，只要我们想引用一个重载或参数化的方法，我们就必须相应地指定其参数的类型。

Consider the following example that refers to an overloaded method:

考虑下面这个例子，它提到了一个重载方法。

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

}

public void move(String direction) {

}

The move() method refers to an overloaded method that takes one String argument.

move()方法指的是一个重载方法，它需要一个String参数。

4. Referencing a Method in Another Class

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

To reference a method in another class, we’ll use the class name, followed by a hashtag, and then the method name:

要引用另一个类中的方法，我们将使用类的名称，后面是一个标签，然后是方法的名称。

{@link ClassName#methodName() LabelName}

The syntax is similar to referencing a method in the same class, in addition to mentioning the class name before the # symbol.

除了在#符号前提到类的名称外，其语法与引用同一类中的方法类似。

Now, let’s consider the example of referencing a method in another class:

现在，让我们考虑引用另一个类中的方法的例子。

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

}

The referenced method is in the Animal class, which is in the same package:

引用的方法在Animal类中，该类在同一个包中。

public void run(String direction) {

}

If we want to reference a method that resides in another package, we have 2 options. One way is to directly specify the package along with the class name:

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

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

}

In this case, the Vehicle class has been mentioned with the complete package name, for referencing the Vehicle() method.

在这种情况下，Vehicle类已经被提到了完整的包名，用于引用Vehicle()方法。

Additionally, we can import the package and mention the class name alone:

此外，我们可以导入包并单独提到类的名字。

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

}

Here, the Car class that resides in another package has been imported. So, the @link only needs to include the class name and method.

这里，驻扎在另一个包中的Car类已经被导入。所以，@link只需要包括类名和方法。

We can choose either of the two ways for referencing methods in a different package. If there is single-time use of the package, then we can go with the first way, otherwise, we should choose the second way if there are multiple dependencies.

我们可以选择这两种方式中的一种来引用不同包中的方法。如果有单次使用包的情况，那么我们可以选择第一种方式，否则，如果有多个依赖关系，我们应该选择第二种方式。

5. The@linkplain Tag

5.@linkplain标签

We’ve seen the @link Javadoc tag for referencing methods in the comments. Javadoc provides another tag named @linkplain for referencing methods in the comments, which is similar to the @link tag. The main difference is that while generating documentation, @link produces the label value in monospaced formatting text, while @linkplain produces it in standard formatting like plain text.

我们已经看到了用于在注释中引用方法的@link Javadoc标签。Javadoc提供了另一个名为@linkplain的标签，用于在注释中引用方法，它与@link标签类似。主要的区别是，在生成文档时，@link以单行线格式文本产生标签值，而@linkplain则以标准格式如纯文本产生。

6. Conclusion

6.结论

In this article, we discussed how to reference methods in Javadoc comments, and we also explored referencing methods in other classes and packages. Lastly, we examined the difference between the @link and @linkplain tags.

在这篇文章中，我们讨论了如何在Javadoc注释中引用方法，我们还探讨了引用其他类和包中的方法。最后，我们研究了@link和@linkplain标签之间的区别。

As always, the code examples of this article can be found over on GitHub.

一如既往，本文的代码示例可以在GitHub上找到over。