Dettagli della differenza tra @see e @inheritDoc

Ho esaminato il riferimento JavaDoc e, sebbene comprenda la differenza di base tra @see(vari collegamenti) e {@inheritDoc}(esportazione del commento JavaDoc della superclasse), ho bisogno di chiarimenti su come le cose sono effettivamente implementate.

Nell'IDE di Eclipse quando seleziono "Genera commenti elemento" per il metodo ereditato (dall'interfaccia, o toString () sovrascrivi e così via) crea il seguente commento

/* (non-Javadoc)
 * @see SomeClass#someMethod()
 */

Se sono tenuto a produrre JavaDoc dovrei lasciare le cose come stanno, sostituire @seecon {@inheritDoc}o trasformarlo in buona fede JavaDoc come tale:

/**
 * {@inheritDoc}
 */

E quando lo faccio, devo comunque mantenere il flag del metodo class #?

java javadoc comments

— theUg
fonte

142

Prima di tutto, dovresti rimuovere il modello di eclissi originale perché è solo spazzatura rumorosa. O inserisci documenti significativi o non inserire nulla. Ma inutile riaffermare l'ovvio usando i modelli IDE ingombra il codice.

In secondo luogo, se si sono tenuti a produrre javadoc, allora si deve fare il commento con inizio /**. Altrimenti, non è javadoc.

Infine, se stai eseguendo l' override, dovresti usare @inheritDoc(supponendo che tu voglia aggiungere ai documenti originali, come @seh ha notato in un commento, se vuoi solo duplicare i documenti originali, allora non hai bisogno di nulla). @seedovrebbe essere utilizzato solo per fare riferimento ad altri metodi correlati.

— jtahlborn
fonte

Dovresti usare solo @inheritDocse intendi aggiungere alla documentazione originale della superclasse. Se vuoi semplicemente che sia duplicato, Javadoc lo farà già, notando che la documentazione della superclasse si applica al metodo sovrascritto della sottoclasse perché la sottoclasse non ha fornito documentazione aggiuntiva.

— seh

Ho generato i documenti con e senza @inheritDoce non vedo alcuna differenza. Anche senza @inheritDoc, vedo che il Javadoc della classe derivata è stato aggiunto alla classe base.

— randominstanceOfLivingThing

Sono venuto qui perché checkstyle si lamenta "il metodo non sembra essere progettato per l'estensione". Una buona idea potrebbe essere quella di utilizzare @inheritDoce quindi aggiungere della documentazione specifica per l'implementazione, ad esempio come implementa / sovrascrive il metodo genitore, e soprattutto PERCHÉ lo fa nel modo in cui lo fa.

— Ben