Question
How can I use the {@link ...} tag in JavaDoc to link to a method?
For example, I want to change this:
/**
* 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()
into something like this:
/**
* 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()
I am not sure what the correct {@link ...} format is when linking to methods in JavaDoc, especially for method calls.
Short Answer
By the end of this page, you will understand how JavaDoc method links work, how to reference methods correctly with {@link ...}, and how to write links for methods in the same class, other classes, and overloaded methods. You will also learn why chaining multiple method links usually needs a slightly different approach than normal Java code.
Concept
JavaDoc uses inline tags like {@link ...} to create clickable references in generated documentation. These links do not work like normal Java expressions. Instead, they point to documented program elements such as:
- classes
- interfaces
- fields
- constructors
- methods
When linking to a method, JavaDoc expects a reference, not an actual executable method call. That means you write the method name and, when needed, its parameter types.
For example:
{@link #getFoo()}
This means:
#→ a member of the current classgetFoo()→ the method being referenced
If the method belongs to another class, include the class name:
{@link Foo#getBar()}
This matters because JavaDoc is meant to generate navigable documentation, not to evaluate code. So when you want to describe a chain like getFoo().getBar().getBaz(), you are really documenting related methods, not calling them.
A good JavaDoc link improves readability and helps readers jump directly to the relevant API details.
Mental Model
Think of JavaDoc {@link ...} as a map reference, not a function call.
- Normal Java code is like driving to a place.
- JavaDoc
{@link ...}is like writing the address in a guidebook.
So this Java code:
getFoo().getBar().getBaz()
actually performs actions.
But this JavaDoc:
{@link #getFoo()}
just points the reader to where getFoo() is documented.
If you want to show a chain of calls in JavaDoc, imagine writing directions in a manual:
- first see
getFoo() - then see
getBar() - then see
getBaz()
You are referencing each stop on the path, not executing the trip.
Syntax and Examples
The basic JavaDoc syntax for linking to methods is:
{@link #methodName()}
For a method in another class:
{@link ClassName#methodName()}
For overloaded methods, include parameter types:
{@link #print(String)}
{@link Math#max(int, int)}
Example: method in the same class
/**
* Returns the user's full name.
* This is a convenience method that combines {@link #getFirstName()} and {@link #getLastName()}.
*/
public String getFullName() {
return getFirstName() + " " + getLastName();
}
Here:
#getFirstName()links to a method in the same class#getLastName()links to another method in the same class
Example: method in another class
/**
* Parses an integer using { Integer#parseInt(String)}.
*/
{
Integer.parseInt(value);
}
Step by Step Execution
Consider this example:
class OrderService {
/**
* Returns the final amount.
* Equivalent to {@link #getOrder()}, then {@link Order#getInvoice()}, then {@link Invoice#getTotal()}.
*/
public double getFinalAmount() {
return getOrder().getInvoice().getTotal();
}
public Order getOrder() {
return new Order();
}
}
Step by step:
-
{@link #getOrder()}#means the current class,OrderService- JavaDoc links to
OrderService.getOrder()
-
{@link Order#getInvoice()}Ordertells JavaDoc to look in theOrderclass- It links to the
getInvoice()method there
Real World Use Cases
Method links in JavaDoc are useful in real projects whenever one method depends on, wraps, or simplifies another method.
1. Convenience methods
A method may combine several smaller methods:
/**
* Convenience method that uses {@link #loadConfig()} and {@link #startServer()}.
*/
2. Wrapper APIs
A public method may delegate to another class:
/**
* Delegates to {@link HttpClient#send(HttpRequest)}.
*/
3. Utility classes
You can point readers to the exact helper method being used:
/**
* Normalizes input using {@link String#trim()}.
*/
4. Framework or library documentation
Library authors often use JavaDoc links so users can jump between related methods quickly.
5. Deprecated method guidance
A deprecated method often links to the replacement:
/**
* @deprecated Use {@link #save(User)} instead.
*/
Real Codebase Usage
In real codebases, developers usually use JavaDoc links in a few common patterns.
Guarding readers toward the right API
If one method should be used instead of another:
/**
* Prefer {@link #createConnection()} for automatic configuration.
*/
Describing delegation
A wrapper method often explains where the real work happens:
/**
* Internally calls {@link Repository#findById(long)}.
*/
Clarifying convenience methods
A method may be a shortcut for a longer sequence:
/**
* Shortcut for calling {@link #open()}, then {@link #read()}, then {@link #close()}.
*/
Documenting overloads precisely
When multiple methods share the same name, developers include parameter types:
/**
* See also {@link #log(String)} and {@link #log(String, Throwable)}.
*/
Pairing links with code formatting
In practice, many teams mix {@link ...} and {@code ...}:
Common Mistakes
1. Forgetting # for methods in the same class
Broken:
{@link getFoo()}
Correct:
{@link #getFoo()}
Why: for members of the current class, JavaDoc expects #methodName().
2. Treating {@link ...} like executable Java code
Broken idea:
{@link #getFoo().getBar().getBaz()}
Why it is wrong:
- JavaDoc cannot evaluate chained method calls inside one link
- a link must point to a single documented element
Correct approach:
{@link #getFoo()}, {@link Foo#getBar()}, {@link Bar#getBaz()}
3. Omitting parameter types for overloaded methods
Broken:
{@link #print()}
This may be ambiguous if there are multiple print methods.
Comparisons
| Feature | {@link ...} | {@code ...} | @see |
|---|---|---|---|
| Purpose | Create clickable inline links | Show code text inline | Add related references in a separate section |
| Clickable | Yes | No | Yes |
| Best for | Referencing classes, methods, fields | Expressions, snippets, literals | Additional related documentation |
| Inline in sentence | Yes | Yes | No, usually block-style |
| Example | {@link #getFoo()} | {@code getFoo().getBar()} |
Cheat Sheet
// Method in same class
{@link #getFoo()}
// Method in another class
{@link Foo#getBar()}
// Overloaded method
{@link #print(String)}
// With custom link label
{@link #getFoo() getFoo()}
{@link Integer#parseInt(String) parseInt}
Rules
- Use
#for members of the current class - Use
ClassName#methodName()for members of another class - Include parameter types for overloaded methods
- Use types, not variable names
- A single
{@link ...}can only reference one program element - For plain code expressions, use
{@code ...}
Good patterns
/**
* See {@link #load()}.
*/
/**
* Delegates to {@link Files#readString(java.nio.file.Path)}.
*/
/**
* Equivalent to {@code getFoo().getBar().getBaz()}.
*/
Important edge case
This is not valid as one link:
{@link #getFoo().getBar()}
FAQ
How do I link to a method in the same class in JavaDoc?
Use {@link #methodName()}. Example:
{@link #getFoo()}
How do I link to a method in another class?
Use {@link ClassName#methodName()}. Example:
{@link Integer#parseInt(String)}
Can I link to a chained call like getFoo().getBar() in one @link?
No. A JavaDoc link can only point to one documented element at a time. Use multiple links or {@code ...} for the full expression.
How do I link to an overloaded method?
Include the parameter types:
{@link #print(String)}
Should I use @link or @code for method chains?
Usually {@code ...} is better for full expressions like getFoo().getBar().getBaz(). Use {@link ...} when you want clickable navigation to a specific API member.
Mini Project
Description
Create a small Java class with several methods and write JavaDoc comments that correctly link related methods. This project helps you practice the difference between linking to a documented method and showing a code expression as plain code text.
Goal
Write clear JavaDoc that uses {@link ...} for method references and {@code ...} for chained expressions.
Requirements
- Create a Java class with at least four methods that call each other
- Add JavaDoc comments that link to methods in the same class
- Include at least one JavaDoc comment that references a method in another class
- Show one chained method call using
{@code ...}instead of trying to put it in a single link
Keep learning
Related questions
Avoiding Java Code in JSP with JSP 2: EL and JSTL Explained
Learn how to avoid Java scriptlets in JSP 2 using Expression Language and JSTL, with examples, best practices, and common mistakes.
Choosing a @NotNull Annotation in Java: Validation vs Static Analysis
Learn how Java @NotNull annotations differ, when to use each one, and how to choose between validation, IDE hints, and static analysis tools.
Convert a Java Stack Trace to a String
Learn how to convert a Java exception stack trace to a string using StringWriter and PrintWriter, with examples and common mistakes.