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!
@seeinMethodB‚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 ...Antworten:
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: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.
quelle
@seeist auch nützlich für die Verknüpfung mit Alternativen zu@DeprecatedMethoden.@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@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.
quelle
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 einenjavadocAbschnitt, in dem die Methode detailliert beschrieben wird, und die überschriebene / implementierte Methode könnte a verwenden@seeTag verwenden, das auf das Basis-Tag verweist.Verwandte Frage: Richtiges Javadoc mit @see schreiben?
Java SE-Dokumentation:
@seequelle
@inheritDockopiert die Dokumentation von einem anderen Speicherort. Ich stelle mir vor, dass es seine Verwendung hat, Details zu beschreiben, anstatt Flusen hinzuzufügen.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@inheritDocund 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.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
quelle