Collegamento Javadoc al metodo in un'altra classe

238

Attualmente sto facendo riferimento a metodi in altre classi con questa sintassi Javadoc:

@see {@link com.my.package.Class#method()}

E in quello che ho capito dalla documentazione questo è il modo corretto di farlo. Ma ora per la parte divertente, o frustrante. Quando genera questo javadoc ricevo innanzitutto il seguente errore:

warning - Tag @see:illegal character: "123" in "{@link com.my.package.Class#method()}"
warning - Tag @see:illegal character: "64" in "{@link com.my.package.Class#method()}"
warning - Tag @see: reference not found: {@link com.my.package.Class#method()}

Il codice HTML generato di questo è:

"," <code>com.my.package.Class#method()}</code> ","

E ovviamente non ho link. Qualcuno può dirmi cosa sta succedendo e qualche suggerimento su come risolvere questo problema?

Secondo la tabella ASCII i caratteri 123 e 64 per wold rappresentano {e @, quindi perché questi caratteri non sono validi quando questa sintassi è corretta secondo la documentazione?

java javadoc

— Roberto
fonte

Solo per controllare ... hai letto la documentazione di Javadoc Generator? docs.oracle.com/javase/7/docs/technotes/tools/windows/…

— Diogo Moreira,

Hai importato com.my.package.Classin classe questo JavaDoc è scritto? Il riferimento non trovato sembra strano. D'altra parte, non li ho mai usati insieme, ma c'è una possibilità che @seesia in @linkconflitto tra loro, prendendo che @seegenera il proprio seciton non mi sorprenderebbe.

— Fritz,

@DiogoMoreira - No, non ho letto del motore, ma lo controllerò.

— Robert,

@Gamb - Ovviamente non è il mio vero input Javadoc ;-) Sì, tutte le importazioni sono a posto.

— Robert,

Un errore simile si verifica se si inserisce un collegamento ipertestuale non elaborato come valore per il @seetag nel proprio javadoc. Per risolvere il problema, in questo caso avvolgere il collegamento ipertestuale in un elemento di ancoraggio html:/** @see <a href="http://example.com">Example</a> */

— cyber-monk

Risposte:

280

Per il tag Javadoc @see, non è necessario utilizzare @link; Javadoc creerà un collegamento per te. Provare

@see com.my.package.Class#method()

Ecco maggiori informazioni su @see.

— rgettman
fonte

Grazie per questo, ho appena testato questa soluzione e funziona benissimo! Ma ho letto in così tanti posti che dovresti usare il link in vedere per farlo funzionare, quindi è un po 'strano ...

— Robert

Puoi utilizzare @linkin altri luoghi che Javadoc non trasforma già in un link, ad esempio nella descrizione per @param, nella descrizione per @return, nella parte principale della descrizione, ecc.

— rgettman,

quando ho appena provato questo visualizza il metodo come testo normale, non è cliccabile come il mio @see per un metodo locale.

— JesseBoyd,

146

A parte @see, è un modo più generale di fare riferimento a un'altra classe e possibilmente metodo di quella classe {@link somepackage.SomeClass#someMethod(paramTypes)}. Questo ha il vantaggio di essere utilizzabile nel mezzo di una descrizione javadoc.

Dalla documentazione javadoc (descrizione del tag @link) :

Questo tag è molto simile a @see: entrambi richiedono gli stessi riferimenti e accettano esattamente la stessa sintassi per il membro package.class # e l'etichetta. La differenza principale è che {@link} genera un collegamento in linea anziché posizionare il collegamento nella sezione "Vedi anche". Inoltre, il tag {@link} inizia e termina con parentesi graffe per separarlo dal resto del testo in linea.

— Javarome
fonte

Quindi la soluzione al problema originale è che non hai bisogno dei riferimenti "@see" e "{@link ...}" sulla stessa riga. Il tag "@link" è autosufficiente e, come notato, puoi inserirlo ovunque nel blocco javadoc. Quindi puoi mescolare i due approcci:

/**
 * some javadoc stuff
 * {@link com.my.package.Class#method()}
 * more stuff
 * @see com.my.package.AnotherClass
 */

— Dave Hentchel
fonte

Questa dovrebbe essere una risposta accettata perché le altre due risposte non mostrano che '@link' o '@vedi' devono essere in un commento a più righe / ** * / non a una riga

— Stoycho Andreev

@Sniper, {@link }funziona bene in un commento Javadoc a riga singola, ti riferisci forse al fatto che non funzionano con i commenti a partire //? /** */è Javadoc ed è necessario per qualsiasi funzione Javadoc.

— Jase,

Sì @Jase Ho incontrato esattamente questo commento deve essere / ** * /, ma non //

— Stoycho Andreev

@Sniper Non penso che ciò richieda che questa sia la risposta accettata perché questa è una domanda Javadoc per cominciare - si dovrebbe generalmente capire che Javadoc funziona solo nei commenti Javadoc.

— Jase,

@Jase è in qualche modo d'accordo con te, ma credo che la fonte di informazioni come StackOverflow abbia bisogno di spiegazioni con esempi non citati dalla documentazione di Oracle o da qualche altra documentazione, il che non è chiaro ovviamente. Questa risposta è l'unica risposta che ha un esempio, sopra due risposte sono citazioni.

— Stoycho Andreev,