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