Parent issue: #19807

Coverage table

Use in-line links economically

Chapter link

Content

Image

Text

Use in-line links economically

You are encouraged to add links for API names (listed immediately above) using the {@link} tag. It is not necessary to add links for all API names in a doc comment. Because links call attention to themselves (by their color and underline in HTML, and by their length in source code doc comments), it can make the comments more difficult to read if used profusely. We therefore recommend adding a link to an API name if:

The user might actually want to click on it for more information (in your judgment), and
Only for the first occurrence of each API name in the doc comment (don't bother repeating a link)
Our audience is advanced (not novice) programmers, so it is generally not necessary to link to API in the java.lang package (such as String), or other API you feel would be well-known.

Guidelines

The relevant parts of the documentation appear to be:

Only for the first occurrence of each API name in the doc comment (don't bother repeating a link)

Our audience is advanced (not novice) programmers, so it is generally not necessary to link to API in the java.lang package (such as String), or other API you feel would be well-known

Currently, there do not seem to be checks covering these cases:

1. ensure only the first occurrence of each API name in a doc comment is linked with {@link}, and later occurrences are not.
2. prevent {@link} tags for APIs from packages that should not be linked, such as java.lang.
3. a configuration option allowing users of the check to define additional packages or APIs that should be treated as “well-known”.

We could create a check to cover these missing cases.