Javadoc @see или {@link}?

Ответ 1

официальные рекомендации об этом довольно ясны.

Функциональные различия:

• {@link} является встроенной ссылкой и может быть размещена там, где вам нравится
• @see создает свой раздел

По-моему, {@link} лучше всего использовать, когда вы буквально используете имя класса, поля, конструктора или метода в своем описании. Пользователь сможет перейти к javadoc того, что вы связали.

Я использую аннотацию @see в двух случаях:

• Что-то очень важно, но не упоминается в описании.
• Я упоминаю одно и то же много раз в описании, и он используется в качестве замены нескольких ссылок на то же самое.

Я основывал это мнение на случайной проверке документации для самых разных вещей в стандартной библиотеке.

Ответ 2

@see создает изолированную строку в Javadocs. {@link} предназначен для встраивания в текст.

Я использую @see, когда это связанный объект, но я не ссылаюсь на него в текстовом тексте. Я использую ссылки в тексте, когда есть тесная связь, или (я чувствую), что, скорее всего, читателю удастся воспользоваться подсказкой навигации, например, вам нужно будет ссылаться на нее напрямую.