Utilizzo di @see in JavaDoc?

110

Quando lo uso @seequando ho a che fare con JavaDocs? Qual è il suo utilizzo?

Per esempio, se MethodAle chiamate MethodBquindi devo mettere @seein MethodB's javadoc e riferimento MethodA, perché questo è ciò che ha chiamato, o devo mettere un riferimento a MethodBda MethodAperché è chiamandolo. Ho letto le cose @seesul sito Oracle e mi sembra che sia incredibilmente vago, dice che significa "vedi anche" ma non proprio cosa significa!

java methods javadoc

— Jeff
fonte

4

mettere @seein MethodB's javadoc e riferimento MethodA, perché questo è ciò che ha chiamato -> Come sarebbe mai possibile conoscere tutti i metodi che richiedono uno dei tuoi metodi? Anche se questo è possibile (diciamo un metodo privato usato solo una volta) il collegamento da chiamato a chiamante suona almeno strano ...

— Mr_and_Mrs_D

1

Significa ciò che di solito significa in inglese: oxforddictionaries.com/us/definition/american_english/see (definizione 1.4)

— stackexchanger

119

Sì, è piuttosto vago.

Dovresti usarlo ogni volta che per i lettori della documentazione del tuo metodo può essere utile guardare anche qualche altro metodo. Se la documentazione del tuo metodoA dice "Funziona come il metodoB ma ...", allora dovresti sicuramente inserire un collegamento. Un'alternativa a @seesarebbe il {@link ...}tag inline :

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

Quando il fatto che il metodoA chiami il metodoB è un dettaglio di implementazione e non esiste una relazione reale dall'esterno, non è necessario un collegamento qui.

— Paŭlo Ebermann
fonte

13

@seeè utile anche per creare collegamenti ad alternative ai @Deprecatedmetodi.

— Mauve Ranger

1

@MauveRanger Dato che @seeè piuttosto vago, per cose deprecate trovo più utile fare qualcosa di più esplicito, come:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Christopher

10

@see è utile per informazioni sui metodi / classi correlati in un'API. Produrrà un collegamento al metodo / codice di riferimento nella documentazione. Usalo quando c'è un codice correlato che potrebbe aiutare l'utente a capire come usare l'API.

— Rob Dawson
fonte

9

Un buon esempio di una situazione in cui @seepuò essere utile potrebbe essere l'implementazione o l'override di un metodo di interfaccia / classe astratta. La dichiarazione avrebbe una javadocsezione che descrive il metodo e il metodo sovrascritto / implementato potrebbe utilizzare un @seetag, che fa riferimento a quello di base.

Domanda correlata: scrivere un javadoc corretto con @see?

Documentazione Java SE: @see

— AtomHeartFather
fonte

2

non ero io, ma probabilmente era perché abbiamo @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

la documentazione java per @see è davvero buona. dovrebbe essere il primo.

— dok

2

@vaxquis @inheritDoccopia la documentazione da un'altra posizione. Immagino che descrivere i dettagli piuttosto che aggiungere lanugine abbia i suoi usi?

— Nielsvh

@Nielsvg questa risposta lo menziona the overridden/implemented method could use a @see tag, referring to the base one.- ed è esattamente a cosa @inheritDocserve; IMO è meglio includere la descrizione della classe di base alla lettera @inheritDoc e integrarla secondo necessità, piuttosto che fare riferimento ad essa con @see- vedere (sic!) Stackoverflow.com/questions/11121600/… ; molti sviluppatori (me compreso) preferiscono avere tutti i dettagli di implementazione in un unico posto, invece di una catena infinita di collegamenti verso l'alto che conducono verso l'alto attraverso una gerarchia di ereditarietà.

2

Uso @see per annotare i metodi di una classe di implementazione dell'interfaccia in cui la descrizione del metodo è già fornita nel javadoc dell'interfaccia. Quando lo facciamo, noto che Eclipse richiama la documentazione dell'interfaccia anche quando cerco il metodo sul riferimento all'implementazione durante il completamento del codice

— Maruthi
fonte