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

Question

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

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

Answer 1

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

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

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

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

Answer 2

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

Answer 3

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

Похожие вопросы: Написание правильного javadoc с @see?

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

Answer 4

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