1. Introduction
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.
2. The @link Tag
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.
Let’s look at the syntax for using the @link tag to reference methods in a Javadoc comment:
{@link path_to_member label}
Similar to the anchor tag, the path_to_member is the destination, and the label is the display text.
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.
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.
3. Referencing a Method in the Same Class
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.
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.
4. Referencing a Method in Another Class
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:
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.
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.
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
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.
6. Conclusion
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.
As always, the code examples of this article can be found over on GitHub.
