Использование @see в JavaDoc?

110

Когда использовать @seeпри работе с JavaDocs? Каково его использование?

Например , если MethodAвызовы , MethodBто я должен поставить @seeв MethodBJavadoc «s и ссылки , MethodAпотому что это то , что называется, или я должен поставить ссылку на MethodBиз , MethodAпотому что звонит его. Я читал материал @seeна веб-сайте Oracle, и он кажется мне невероятно расплывчатым, в нем говорится, что это означает «также увидеть», но не совсем то, что это означает!

java methods javadoc

— Джефф
источник

4

поместить @seeв MethodB«s Javadoc и ссылки , MethodAпотому что это то , что называется это -> Как бы когда - нибудь возможно знать все методы , которые требуют один из ваших методов? Даже если это возможно (скажем, частный метод используется только один раз), связывание от вызываемого к вызывающему звучит как минимум странно ...

— Mr_and_Mrs_D

1

Это означает то, что обычно означает по-английски: oxford dictionaries.com/us/definition/american_english/see (определение 1.4)

— stackexchanger

119

Да, довольно расплывчато.

Вы должны использовать его всякий раз, когда читателям документации вашего метода может быть полезно также взглянуть на какой-либо другой метод. Если в документации к вашему методу A написано: «Работает как метод B, но ...», то вы обязательно должны поместить ссылку. Альтернативой @seeможет быть встроенный {@link ...}тег:

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

Когда тот факт, что methodA вызывает methodB, является деталью реализации и нет никакой реальной связи извне, вам здесь не нужна ссылка.

— Пало Эберманн
источник

13

@seeтакже полезно для ссылки на альтернативные @Deprecatedметоды.

— Mauve Ranger

1

@MauveRanger Поскольку @seeэто довольно расплывчато, для устаревших вещей я считаю более полезным сделать что-то более явное, например:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Кристофер

10

@see полезен для получения информации о связанных методах / классах в API. Будет создана ссылка на указанный метод / код в документации. Используйте его, когда есть связанный код, который может помочь пользователю понять, как использовать API.

— Роб Доусон
источник

9

Хорошим примером ситуации, когда @seeможет быть полезно, может быть реализация или переопределение метода интерфейса / абстрактного класса. Объявление будет иметь javadocраздел с подробным описанием метода, а переопределенный / реализованный метод может использовать @seeтег, относящийся к базовому.

Связанный вопрос: Написание правильного javadoc с помощью @see?

Документация Java SE: @see

— AtomHeartFather
источник

2

это был не я, но, вероятно, потому что у нас есть @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

документация java для @see действительно хороша. должен быть первым.

— док

2

@vaxquis @inheritDocкопирует документацию из другого места. Я полагаю, что описание деталей, а не добавление пустяков, имеет свое применение?

— Nielsvh 01

@Nielsvg этот ответ упоминает это the overridden/implemented method could use a @see tag, referring to the base one.- и это именно то @inheritDoc, для чего; ИМО, лучше дословно включить описание базового класса @inheritDoc и при необходимости дополнить его, чем ссылаться на него @see- см. (Sic!) Stackoverflow.com/questions/11121600/… ; многие разработчики (в том числе и я) предпочитают хранить все детали реализации в одном месте, вместо бесконечной цепочки восходящих ссылок, ведущих вверх по иерархии наследования.

2

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

— Maruthi
источник