Javadoc @see lub {@link}?

184

Czy ktoś mógłby mi powiedzieć różnicę między javadoc @seea {@link}?

A raczej, kiedy użyć którego z nich?

java javadoc

— Membersound
źródło

213

Te oficjalne wytyczne na ten temat są dość jasne.

Różnice funkcjonalne to:

{@link} to link wbudowany i można go umieścić w dowolnym miejscu
@see tworzy własną sekcję

Moim zdaniem {@link}najlepiej używać, gdy dosłownie używasz nazwy opisu, klasy, konstruktora lub metody. Użytkownik będzie mógł kliknąć javadoc tego, co zostało połączone.

@seeAdnotacji używam w 2 przypadkach:

Coś jest bardzo istotne, ale nie wspomniane w opisie.
Odnoszę się do tego samego wiele razy w opisie i jest on stosowany jako zamiennik wielu linków do tego samego.

Oparłem tę opinię na losowym sprawdzaniu dokumentacji dla wielu różnych rzeczy w standardowej bibliotece.

— MarioDS
źródło

3

Jawadoc ostrzega, że @link jest dość intensywny i powinien być używany tylko w razie potrzeby.

— Thomas

4

Dla każdego, kto szuka, możesz uzyskać szczegółowe informacje na ten temat (w tym ostrzeżenie @linkw komentarzu powyżej) w przewodniku Oracle Javadoc .

— Ash Ryan Arnwine,

48

@seetworzy izolowaną linię w Javadocs. {@link}służy do osadzania w tekście.

Używam, @seegdy jest to podmiot powiązany, ale nie odwołuję się do niego w tekście ekspozycyjnym. Używam linków w tekście, gdy występuje ścisłe sprzężenie lub (wydaje mi się, że) czytelnik skorzystałby na wskazówkach nawigacyjnych, np. Będziesz musiał odwoływać się do niego bezpośrednio.

— Dave Newton
źródło

3

Nie ma innego odniesienia (sekcja deprecation) same oficjalne docs wolą {@link}ponad @see(od Java 1.2):

W Javadoc 1.2 i nowszych standardowym formatem jest użycie znacznika @deprecated i wbudowanego znacznika {@link}. Spowoduje to utworzenie łącza bezpośrednio tam, gdzie chcesz. Na przykład:

W Javadoc 1.1 standardowym formatem jest utworzenie pary tagów @deprecated i @see. Na przykład:

— użytkownik7294900
źródło