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

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

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

Ответы

Ответ 1

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

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

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

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

Ответ 2

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

Ответ 3

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

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

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

Ответ 4

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