Javadoc @see o {@link}?

Qualcuno potrebbe dirmi la differenza tra javadoc @seee {@link}?

O meglio, quando usare quale di loro?

Le linee guida ufficiali su questo sono abbastanza chiare.

Le differenze funzionali sono:

• {@link} è un collegamento in linea e può essere posizionato dove vuoi
• @see crea una propria sezione

Secondo me, {@link}è meglio usarlo quando usi letteralmente una classe, un campo, un costruttore o un nome di metodo nella tua descrizione. L'utente sarà in grado di fare clic per accedere al javadoc di ciò che è stato collegato.

Uso l' @seeannotazione in 2 casi:

• Qualcosa è molto rilevante ma non menzionato nella descrizione.
• Mi riferisco alla stessa cosa più volte nella descrizione e viene utilizzato in sostituzione di più collegamenti alla stessa.

Ho basato questa opinione sul controllo casuale della documentazione per una grande varietà di cose nella libreria standard.

@seecrea una linea isolata in Javadocs. {@link}è per l'incorporamento nel testo.

Uso @seequando è un'entità correlata ma non mi riferisco ad essa nel testo dell'espositore. Uso i collegamenti all'interno del testo in caso di accoppiamento stretto o (credo) è probabile che il lettore trarrebbe beneficio dal suggerimento di navigazione, ad esempio, è necessario fare riferimento direttamente a esso.

C'è un altro riferimento (sezione deprecazione) stessi documenti ufficiali a preferire {@link}sopra @see(dal Java 1.2):

Per Javadoc 1.2 e versioni successive, il formato standard prevede l'utilizzo del tag @deprecated e del tag {@link} in linea. Questo crea il collegamento in linea, dove lo desideri. Per esempio:

Per Javadoc 1.1, il formato standard è quello di creare una coppia di tag @deprecated e @see. Per esempio: