Когда использовать @seeпри работе с JavaDocs? Каково его использование?
Например , если MethodAвызовы , MethodBто я должен поставить @seeв MethodBJavadoc «s и ссылки , MethodAпотому что это то , что называется, или я должен поставить ссылку на MethodBиз , MethodAпотому что звонит его. Я читал материал @seeна веб-сайте Oracle, и он кажется мне невероятно расплывчатым, в нем говорится, что это означает «также увидеть», но не совсем то, что это означает!
@seeвMethodB«s Javadoc и ссылки ,MethodAпотому что это то , что называется это -> Как бы когда - нибудь возможно знать все методы , которые требуют один из ваших методов? Даже если это возможно (скажем, частный метод используется только один раз), связывание от вызываемого к вызывающему звучит как минимум странно ...Ответы:
Да, довольно расплывчато.
Вы должны использовать его всякий раз, когда читателям документации вашего метода может быть полезно также взглянуть на какой-либо другой метод. Если в документации к вашему методу A написано: «Работает как метод B, но ...», то вы обязательно должны поместить ссылку. Альтернативой
@seeможет быть встроенный{@link ...}тег:Когда тот факт, что methodA вызывает methodB, является деталью реализации и нет никакой реальной связи извне, вам здесь не нужна ссылка.
источник
@seeтакже полезно для ссылки на альтернативные@Deprecatedметоды.@seeэто довольно расплывчато, для устаревших вещей я считаю более полезным сделать что-то более явное, например:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead@see полезен для получения информации о связанных методах / классах в API. Будет создана ссылка на указанный метод / код в документации. Используйте его, когда есть связанный код, который может помочь пользователю понять, как использовать API.
источник
Хорошим примером ситуации, когда
@seeможет быть полезно, может быть реализация или переопределение метода интерфейса / абстрактного класса. Объявление будет иметьjavadocраздел с подробным описанием метода, а переопределенный / реализованный метод может использовать@seeтег, относящийся к базовому.Связанный вопрос: Написание правильного javadoc с помощью @see?
Документация Java SE:
@seeисточник
@inheritDocкопирует документацию из другого места. Я полагаю, что описание деталей, а не добавление пустяков, имеет свое применение?the overridden/implemented method could use a @see tag, referring to the base one.- и это именно то@inheritDoc, для чего; ИМО, лучше дословно включить описание базового класса@inheritDocи при необходимости дополнить его, чем ссылаться на него@see- см. (Sic!) Stackoverflow.com/questions/11121600/… ; многие разработчики (в том числе и я) предпочитают хранить все детали реализации в одном месте, вместо бесконечной цепочки восходящих ссылок, ведущих вверх по иерархии наследования.Я использую @see для аннотирования методов класса реализации интерфейса, где описание метода уже предоставлено в javadoc интерфейса. Когда мы это делаем, я замечаю, что Eclipse открывает документацию по интерфейсу, даже когда я ищу метод в ссылке на реализацию во время завершения кода.
источник