Когда я использую @see при работе с JavaDocs? Каково его использование?
Например, если MethodA вызывает MethodB, тогда мне нужно поставить @see в MethodB javadoc и ссылку MethodA, потому что это то, что называется, или мне нужно поместить ссылку на MethodB от MethodA, потому что он его вызывает. Я прочитал материал о @see на веб-сайте Oracle, и мне кажется, что он невероятно расплывчатый, он говорит, что это означает "см. Также", но на самом деле это не значит!
Да, это довольно расплывчато.
Вы должны использовать его, когда для читателей документации вашего метода может быть полезно также посмотреть на какой-либо другой метод. Если в документации вашего методаA говорится: "Работает как methodB, но...", вы обязательно должны поместить ссылку.
Альтернативой @see будет встроенный тег {@link ...}:
/**
* ...
* Works like {@link #methodB}, but ...
*/
Когда тот факт, что методA вызывает методB, является деталью реализации и нет реального отношения снаружи, вам здесь не нужна ссылка.
@see полезен для информации о связанных методах/классах в API. Он подготовит ссылку на ссылочный метод/код в документации. Используйте его, когда есть связанный код, который может помочь пользователю понять, как использовать API.
Хорошим примером ситуации, когда @see может быть полезно, будет реализация или переопределение метода интерфейса/абстрактного класса. Объявление должно содержать раздел javadoc, подробно описывающий метод, а метод overridden/Implement может использовать тег @see, ссылаясь на базовый.
Связанный вопрос: Написание собственного javadoc с помощью @see?
Документация по Java SE: @see
Я использую @see для аннотирования методов класса реализации интерфейса, где описание метода уже представлено в javadoc интерфейса. Когда мы это делаем, я замечаю, что Eclipse подтягивает документацию интерфейса, даже когда я ищу метод для ссылки на реализацию во время завершения кода