Javadoc @see or {@link}?

Question

The official guidelines on this are pretty clear.

The functional differences are:

• {@link} is an inline link and can be placed wherever you like
• @see creates its own section

In my opinion, {@link} is best used when you literally use a class, field, constructor or method name in your description. The user will be able to click through to the javadoc of what you've linked.

I use the @see annotation in 2 cases:

• Something is very relevant but not mentioned in the description.
• I refer to the same thing multiple times in the description, and it is used as a replacement for multiple links to the same.

I based this opinion on randomly checking out documentation for a great variety of things in the standard library.

@see creates an isolated line in the Javadocs. {@link} is for embedding within text.

I use @see when it's a related entity but I don't refer to it in the expository text. I use links within text when there's tight coupling, or (I feel) it's likely the reader would benefit from the navigation hint, e.g., you'll need to reference it directly.

There's another reference (deprecation section) same official docs to prefer {@link} over @see (since Java 1.2):

For Javadoc 1.2 and later, the standard format is to use @deprecated tag and the in-line {@link} tag. This creates the link in-line, where you want it. For example:

For Javadoc 1.1, the standard format is to create a pair of @deprecated and @see tags. For example:

The @see tag is a bit different than the @link tag,
limited in some ways and more flexible in others:

^{Different JavaDoc link types}

1. Displays the member name for better learning, and is refactorable; the name will update when renaming by refactor
2. Refactorable and customizable; your text is displayed instead of the member name
3. Displays name, refactorable
4. Refactorable, customizable
5. A rather mediocre combination that is:

• Refactorable, customizable, and stays in the See Also section
• Displays nicely in the Eclipse hover
• Displays the link tag and its formatting when generated 😞
• When using multiple @see items, commas in the description make the output confusing

6. Completely illegal; causes unexpected content and illegal character errors in the generator

See the results below:

^{JavaDoc generation results with different link types}

Best regards.