CODEWITHSUNDEEP
javajavadoc
membersound
membersound

Reputation: 86847

Javadoc @see or {@link}?

Could someone tell me the difference between javadoc @see and {@link}?

Or rather, when to use which of them?

Upvotes: 213

Views: 122453

Answers (4)

nikodaemus
nikodaemus

Reputation: 2128

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

different JavaDoc link types 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
  1. Completely illegal; causes unexpected content and illegal character errors in the generator

See the results below:

JavaDoc generation results with different link types JavaDoc generation results with different link types

Best regards.

Upvotes: 14

Ori Marko
Ori Marko

Reputation: 58812

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:

Upvotes: 5

MarioDS
MarioDS

Reputation: 13063

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.

Upvotes: 241

Dave Newton
Dave Newton

Reputation: 160261

@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.

Upvotes: 55

Related Questions