it-swarm-ru.tech

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

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

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

92
Jeff

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

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

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

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

102
Paŭlo Ebermann

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

10
Rob Dawson

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

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

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

8
AtomHeartFather

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

2
Maruthi