Javadoc @see чи {@link}?

184

Може хтось скаже мені різницю між javadoc @seeі {@link}?

А точніше, коли використовувати який із них?

java javadoc

— члени Звуку
джерело

213

В офіційних рекомендаціях з цього питання досить ясні.

Функціональні відмінності:

{@link} є вбудованим посиланням і може бути розміщений де завгодно
@see створює власний розділ

На мою думку, {@link}найкраще використовувати, коли ви буквально використовуєте у своєму описі назву класу, поля, конструктора чи методу. Користувач зможе перейти до javadoc того, що ви пов’язали.

Я використовую @seeпримітку у 2 випадках:

Щось дуже актуальне, але не описується в описі.
Я посилаюся на одне і те ж саме кілька разів в описі, і воно використовується як заміна декількох посилань на одне і те ж.

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

— MarioDS
джерело

3

Javadoc дійсно попереджає, що @link досить інтенсивний, і його слід використовувати лише в разі необхідності.

— Томас

4

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

— Еш Райан Арнвін

48

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

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

— Дейв Ньютон
джерело

3

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

Для Javadoc 1.2 і пізніших версій стандартним форматом є використання тегу @deprecated та тега рядка {@link}. Це створює посилання в рядку, де ви хочете. Наприклад:

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

— user7294900
джерело