Javadoc @see или {@link}?

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

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

3 ответов


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

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

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

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

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

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

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


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

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


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

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

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