Javadoc @ смотри или {@link}?

184

Может кто-нибудь сказать мне разницу между Javadoc @seeи {@link}?

Вернее, когда использовать какой из них?

java javadoc

— membersound
источник

213

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

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

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

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

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

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

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

— MarioDS
источник

3

Javadoc предупреждает, что @link довольно интенсивен и должен использоваться только при необходимости.

— Томас

4

Для тех, кто ищет, вы можете получить подробную информацию об этом (включая предупреждение @linkв комментарии выше) в руководстве Oracle по Javadoc .

— Эш Райан Арнвейн

48

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

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

— Дэйв Ньютон
источник

3

Там еще одна ссылка (неодобрение раздел) же официальные документы предпочитают {@link}более @see(с Java 1.2):

Для Javadoc 1.2 и более поздних версий стандартным форматом является использование тега @deprecated и встроенного тега {@link}. Это создает ссылку в строке, где вы хотите. Например:

Для Javadoc 1.1 стандартным форматом является создание пары тегов @deprecated и @see. Например:

— user7294900
источник