Javadoc @see oder {@link}?

184

Könnte mir jemand den Unterschied zwischen Javadoc @seeund Javadoc sagen {@link}?

Oder eher, wann welche davon zu verwenden sind?

Mitgliedssound
quelle

Antworten:

213

Die offiziellen Richtlinien dazu sind ziemlich klar.

Die funktionalen Unterschiede sind:

  • {@link} ist ein Inline-Link und kann platziert werden, wo immer Sie möchten
  • @see erstellt einen eigenen Abschnitt

Meiner Meinung nach wird {@link}es am besten verwendet, wenn Sie in Ihrer Beschreibung buchstäblich einen Klassen-, Feld-, Konstruktor- oder Methodennamen verwenden. Der Benutzer kann sich zum Javadoc Ihrer Verknüpfung durchklicken.

Ich benutze die @seeAnmerkung in 2 Fällen:

  • Etwas ist sehr relevant, wird aber in der Beschreibung nicht erwähnt.
  • Ich beziehe mich in der Beschreibung mehrmals auf dasselbe und es wird als Ersatz für mehrere Links zu demselben verwendet.

Ich habe diese Meinung auf das zufällige Auschecken der Dokumentation für eine Vielzahl von Dingen in der Standardbibliothek gestützt.

MarioDS
quelle
3
Der Javadoc warnt, dass @link ziemlich intensiv ist und nur bei Bedarf verwendet werden sollte.
Thomas
4
Für alle, die suchen, finden Sie Details dazu (einschließlich der Warnung @linkim obigen Kommentar) im Javadoc-Handbuch von Oracle .
Ash Ryan Arnwine
48

@seeerstellt eine isolierte Linie in den Javadocs. {@link}dient zum Einbetten in Text.

Ich verwende es, @seewenn es sich um eine verwandte Entität handelt, verweise jedoch im Expository-Text nicht darauf. Ich verwende Links innerhalb von Text, wenn eine enge Kopplung besteht, oder (ich glaube) es ist wahrscheinlich, dass der Leser von dem Navigationshinweis profitieren würde, z. B. müssen Sie direkt darauf verweisen.

Dave Newton
quelle
3

Es gibt eine weitere Referenz (deprecation Abschnitt) gleiche offizielle Dokumentation bevorzugen {@link}über @see(seit Java 1.2):

Für Javadoc 1.2 und höher besteht das Standardformat darin, das @deprecated-Tag und das Inline-Tag {@link} zu verwenden. Dadurch wird der Link inline erstellt, wo Sie ihn möchten. Beispielsweise:

Für Javadoc 1.1 besteht das Standardformat darin, ein Paar von @deprecated- und @see-Tags zu erstellen. Beispielsweise:

user7294900
quelle