Javadoc @see or {@link}?
JavaJavadocJava Problem Overview
Could someone tell me the difference between javadoc @see
and {@link}
?
Or rather, when to use which of them?
Java Solutions
Solution 1 - Java
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.
Solution 2 - Java
@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.
Solution 3 - Java
The @see
tag is a bit different than the @link
tag,
limited in some ways and more flexible in others:
- Displays the member name for better learning, and is refactorable; the name will update when renaming by refactor
- Refactorable and customizable; your text is displayed instead of the member name
- Displays name, refactorable
- Refactorable, customizable
- 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
- 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.
Solution 4 - Java
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: