Linking to External URLs in Javadoc

You will learn that {@link} is for Java API elements, while an HTML <a> tag is the usual way to link to an external website in Javadoc. You will also see when @see is a useful alternative.

Javadoc comments describe Java code and can be converted into HTML API documentation.

The inline {@link ...} tag creates a link to a Java program element such as a class, method, field, package, or module. For example, it can link to java.util.List or String#length().

An external web address is not a Java program element, so {@linktourl ...} is not a built-in Javadoc tag. To link to an external site in descriptive text, use a standard HTML anchor:

<a href="https://www.google.com/">Google</a>

Javadoc supports a limited, documentation-oriented subset of HTML. Anchors are useful when readers need a source, specification, vendor page, or other resource outside the generated API documentation.

Think of generated Javadoc as a local library catalogue:

• {@link} points to another item inside the catalogue—a Java class or method.
• <a href="..."> points to a destination outside the catalogue—a website.
• @see adds an item to a separate See Also list.

Choose the kind of link based on where the reader needs to go.

Use an HTML anchor for an external URL:

/**
 * Search for documentation using
 * <a href="https://www.google.com/">Google</a>.
 */
public void search() {
}

The text between <a ...> and </a> becomes the clickable label. The href attribute contains the destination URL.

Use {@link} for Java code references:

/**
 * Stores results in a {@link java.util.List}.
 */
public void saveResults() {
}

You can also provide a friendlier label for a Java reference:

/**
 * Calls {@link String#trim() remove surrounding whitespace}.
 */
public String clean(String input) {
    return input.trim();
}

For an external resource in a dedicated See Also section, use @see with an anchor:

Consider this method documentation:

/**
 * Validates a user-supplied address.
 * For URI rules, see <a href="https://www.rfc-editor.org/rfc/rfc3986">RFC 3986</a>.
 */
public boolean isValidAddress(String address) {
    return address != null && !address.isBlank();
}

When Javadoc runs:

1. It reads the /** ... */ documentation comment above isValidAddress.
2. It keeps the descriptive text as part of the method documentation.
3. It recognizes the HTML <a> element.
4. It generates HTML containing a hyperlink whose destination is https://www.rfc-editor.org/rfc/rfc3986.
5. A reader viewing the generated documentation can select RFC 3986 to open the external resource.

The Java method itself runs normally; the link affects generated documentation only.

External links in Javadoc are useful for:

• Linking to an official protocol or file-format specification, such as an RFC.
• Linking to vendor documentation for an external service or SDK.
• Linking to a public standards page that defines terms used by your API.
• Linking to a project migration guide or compatibility policy.
• Linking to a public security advisory or requirements document.

For example, a method that verifies a UUID can point to the relevant standard:

/**
 * Checks whether text has the UUID format defined by
 * <a href="https://www.rfc-editor.org/rfc/rfc4122">RFC 4122</a>.
 */
public boolean isUuid(String value) {
    return value != null && value.matches("[0-9a-fA-F-]{36}");
}

In production projects, developers usually use each link type for a distinct purpose:

• Use {@link} when referring to code maintained in the same API or available on the Javadoc classpath.
• Use {@linkplain} when the Java reference should appear as plain text rather than monospaced code text.
• Use an HTML <a> element for a public external URL within a sentence.
• Use @see when the resource is supplementary and belongs in a separate related-links area.

A common pattern combines an implementation link with an external specification:

/**
 * Parses a URI with {@link java.net.URI}.
 *
 * <p>The accepted URI syntax follows
 * <a href="https://www.rfc-editor.org/rfc/rfc3986">RFC 3986</a>.</p>
 *
 * @see java.net.URI
 */
public java.net.URI parseUri(String text) {
    return java.net.URI.create(text);
}

Prefer stable, authoritative https:// links. If an external page moves, update the Javadoc so generated documentation does not contain stale references.

Using a made-up Javadoc tag

This is not a standard Javadoc inline tag:

/**
 * See {@linktourl http://google.com}
 */

Use an HTML anchor instead:

/**
 * See <a href="https://www.google.com/">Google</a>.
 */

Using {@link} with a web URL

{@link} is intended for Java references, not general web links:

/**
 * Incorrect: {@link https://www.google.com/}
 */

Use <a href="...">...</a> for an external destination.

Omitting the closing anchor tag

Broken HTML can make the rest of the documentation render incorrectly:

/**
 * Visit <a href="https://example.com">Example.
 */

Always close the anchor:

/**
 * Visit <a href="https://example.com">Example</a>.
 */

Using an unclear link label

Avoid labels such as or a raw, long URL when a meaningful description is possible:

// External URL in Javadoc text
/**
 * Read <a href="https://example.com">the guide</a>.
 */

// Link to a Java class
/**
 * Uses {@link java.util.List}.
 */

// Link to a Java method, with a custom label
/**
 * Calls {@link String#isBlank() checks for blank text}.
 */

// External resource in the See Also section
/**
 * @see <a href="https://example.com">External guide</a>
 */

Rules:

• Use <a href="URL">label</a> for external sites.
• Use {@link} and {@linkplain} for Java API references.
• Prefer https:// URLs.
• Use descriptive link text.
• Ensure every HTML anchor has a closing </a> tag.

Can I use {@link} to link to Google or another website?

No. {@link} is for references to Java program elements such as classes and methods. Use an HTML <a> tag for a general external URL.

What is the correct syntax for an external link in Javadoc?

Use an anchor element:

<a href="https://example.com">Example</a>

Can I put an external URL in an @see tag?

Yes. Use an anchor inside @see:

@see <a href="https://example.com">Example documentation</a>

What is the difference between @link and @linkplain?

Both link to Java program elements. {@link} normally uses code-style formatting, while {@linkplain} uses plain-text formatting.

Should I use http or https in Javadoc links?

Use whenever the destination supports it. It provides encrypted connections and is the normal choice for public documentation.

• Javadoc comments — The /** ... */ comment format used to document Java APIs.
• Inline Javadoc tags — Tags such as {@link} that add structured content inside prose.
• @see tag — Adds related classes, methods, or external references to a See Also section.
• HTML anchors — The <a href="..."> element used to create hyperlinks.
• Java API references — Class and member references such as String#trim() used by {@link}.
• Javadoc generation — The process of converting Java source documentation into browsable HTML pages.