Verwendung von @see in JavaDoc?

110

Wann verwende ich @seebeim Umgang mit JavaDocs? Was ist seine Verwendung?

Zum Beispiel , wenn MethodAAnrufe MethodBtun , dann muss ich setzen @seein MethodB‚s javadoc und Referenz , MethodAweil das , was sie genannt wird, oder muss ich einen Verweis setzen MethodBaus , MethodAweil sie es anruft. Ich habe das Zeug @seeauf der Oracle-Website gelesen und es scheint mir unglaublich vage zu sein. Es heißt "siehe auch", aber nicht wirklich, was das bedeutet!

java methods javadoc

— Jeff
quelle

4

setzen @seein MethodB‚s javadoc und Referenz , MethodAweil das , was es heißt -> Wie wäre immer möglich , alle Methoden zu kennen , die eine Ihrer Methoden aufrufen? Selbst wenn dies möglich ist (sagen wir eine private Methode, die nur einmal verwendet wird), klingt die Verknüpfung von Angerufenen zu Anrufern zumindest seltsam ...

— Mr_and_Mrs_D

1

Es bedeutet, was es normalerweise auf Englisch bedeutet: oxforddictionaries.com/us/definition/american_english/see (Definition 1.4)

— Stackexchanger

119

Ja, es ist ziemlich vage.

Sie sollten es immer dann verwenden, wenn es für Leser der Dokumentation Ihrer Methode nützlich sein kann, sich auch eine andere Methode anzusehen. Wenn in der Dokumentation Ihrer Methode A "Funktioniert wie Methode B, aber ..." steht, sollten Sie auf jeden Fall einen Link einfügen. Eine Alternative zu @seewäre das Inline- {@link ...}Tag:

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

Wenn die Tatsache, dass methodA methodB aufruft, ein Implementierungsdetail ist und es keine echte Beziehung von außen gibt, benötigen Sie hier keinen Link.

— Paŭlo Ebermann
quelle

13

@seeist auch nützlich für die Verknüpfung mit Alternativen zu @DeprecatedMethoden.

— Mauve Ranger

1

@MauveRanger Da @seees ziemlich vage ist, finde ich es für veraltete Sachen nützlicher, etwas expliziteres zu tun, wie:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Christopher

10

@see ist nützlich, um Informationen zu verwandten Methoden / Klassen in einer API zu erhalten. Es wird ein Link zu der Methode / dem Code erstellt, auf die / den in der Dokumentation verwiesen wird. Verwenden Sie es, wenn verwandter Code vorhanden ist, der dem Benutzer möglicherweise hilft, die Verwendung der API zu verstehen.

— Rob Dawson
quelle

9

Ein gutes Beispiel für eine Situation, in der @seedies nützlich sein kann, ist das Implementieren oder Überschreiben einer Schnittstellen- / abstrakten Klassenmethode. Die Deklaration hätte einen javadocAbschnitt, in dem die Methode detailliert beschrieben wird, und die überschriebene / implementierte Methode könnte a verwenden@see Tag verwenden, das auf das Basis-Tag verweist.

Verwandte Frage: Richtiges Javadoc mit @see schreiben?

Java SE-Dokumentation: @see

— AtomHeartFather
quelle

2

war nicht ich, aber es war wahrscheinlich, weil wir @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

Die Java-Dokumentation für @see ist wirklich gut. sollte zuerst sein.

— dok

2

@vaxquis @inheritDockopiert die Dokumentation von einem anderen Speicherort. Ich stelle mir vor, dass es seine Verwendung hat, Details zu beschreiben, anstatt Flusen hinzuzufügen.

— Nielsvh

@Nielsvg diese Antwort erwähnt das the overridden/implemented method could use a @see tag, referring to the base one.- und genau dafür @inheritDocist; IMO ist es besser , die Basisklasse Beschreibung wörtlich mittels aufzunehmen @inheritDoc und ergänzen sie je nach Bedarf, als von ihm zu beziehen @see- siehe (sic!) Stackoverflow.com/questions/11121600/... ; Viele Entwickler (ich eingeschlossen) bevorzugen es, alle Implementierungsdetails an einem Ort zu haben, anstatt eine endlose Kette von Aufwärtsverbindungen, die durch eine Vererbungshierarchie nach oben führen.

2

Ich benutze @see, um Methoden einer Schnittstellenimplementierungsklasse zu kommentieren, bei der die Beschreibung der Methode bereits im Javadoc der Schnittstelle enthalten ist. Wenn wir das tun, bemerke ich, dass Eclipse die Dokumentation der Schnittstelle aufruft, selbst wenn ich während des Code-Abschlusses nach der Methode in der Implementierungsreferenz suche

— Maruthi
quelle