Javadoc @see lub {@link}?

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

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

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.

@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.

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: