Javadoc is used to generate API documentation in HTML format using Java code.

Using HTML format makes it easy to link related pieces of documentation together.

Java developers are sometimes confused about which type of link annotation ({@link} or @see) to use within their API documentation. Let’s clarify this…

Functionally,

• {@link} gives you an inline link which you can place anywhere you want.
• @see creates a section of its own.

Generally, when you use a field, class, method, or constructor name literally in your description, it is best to use {@link}.

Users will be able to click through to see the javadoc of what was linked.

Use cases for @see include:

• Linking to some relevant information that isn’t mentioned in the description.
• When you refer to the same thing multiple times in description, you can use @see instead of multiple links.

So, in most cases where a link annotation is needed, {@link} is probably what you want.

Note however, that Oracle’s official javadoc guide warns that {@link} should be used only when necessary since it is rather intensive.

And since the target audience are advanced programmers (not newbies), it is usually not necessary to link to basic API in the java.lang package (basic stuff like String). Such API are expected to be already well-known.