Використання @see в JavaDoc?

110

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

Наприклад , якщо MethodAвиклики , MethodBто я повинен поставити @seeв MethodBJavadoc «s і посилання , MethodAтому що це те , що називається, або я повинен поставити посилання на MethodBз , MethodAтому що дзвонить його. Я читав речі @seeна веб-сайті Oracle, і мені здається, це неймовірно розпливчасто, це говорить про те, що це означає «бачити також», але не дуже, що це означає!

java methods javadoc

— Джефф
джерело

4

поставити @seeв MethodB's javadoc і посилання, MethodAтому що саме так його називали -> Як можна було б дізнатися всі методи, які викликають один із ваших методів? Навіть якщо це можливо (скажімо, приватний метод, що використовується лише один раз), прив'язка від виклику до абонента звучить принаймні дивно ...

— Mr_and_Mrs_D

1

Це означає, що це зазвичай означає англійською мовою: oxforddic slova.com/us/definition/american_english/see (визначення 1.4)

— stackexchanger

119

Так, це зовсім невиразно.

Ви повинні використовувати його щоразу, коли читачам документації вашого методу може бути корисно також ознайомитись з іншим методом. Якщо в документації вашого методуA написано "Працює, як methodB, але ...", то вам неодмінно слід покласти посилання. Альтернативою @seeможе бути вбудований {@link ...}тег:

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

Якщо той факт, що methodA викликає methodB, є детальною інформацією про реалізацію і немає реального відношення ззовні, вам тут не потрібно посилання.

— Паоло Еберман
джерело

13

@seeтакож корисний для посилання на альтернативи @Deprecatedметодам.

— Mauve Ranger

1

@MauveRanger Оскільки @seeдосить розпливчасто, для застарілих речей я вважаю кориснішим зробити щось більш чітке, як-от:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Крістофер

10

@see корисний для інформації про пов'язані методи / класи в API. Він створить посилання на посилається на метод / код документації. Використовуйте його, коли є відповідний код, який може допомогти користувачеві зрозуміти, як користуватися API.

— Роб Доусон
джерело

9

Хорошим прикладом ситуації, коли @seeможе бути корисною, буде реалізація або переопределення методу інтерфейсу / абстрактного класу. У декларації javadocміститься розділ, що детально описує метод, а переоформлений / реалізований метод може використовувати a@see тег, посилаючись на базовий.

Пов’язане запитання: Написання належного javadoc за допомогою @see?

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

— AtomHeartFather
джерело

2

не я, але, мабуть, тому, що у нас є @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

документація Java для @see - справді хороша. має бути першим.

— ДОК

2

@vaxquis @inheritDocкопіює документацію з іншого місця розташування. Я гадаю, що опис деталей, а не додавання пух має свою користь?

— Nielsvh

@Nielsvg ця відповідь зазначає, що the overridden/implemented method could use a @see tag, referring to the base one.- і саме @inheritDocдля цього і є; ІМО краще включити опис базового класу дослівно за допомогою @inheritDoc та доповнити його за потребою, ніж посилатися на нього за допомогою @see- див. (Sic!) Stackoverflow.com/questions/11121600/… ; багато розробників (включаючи мене) вважають за краще, щоб усі деталі реалізації були в одному місці, а не постійні ланцюги висхідних посилань, що ведуть вгору через ієрархію спадкування.

2

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

— Маруті
джерело