Search code examples
javajavadoc

Javadoc @see or {@link}?

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

Or rather, when to use which of them?

Solution

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