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
источник