Detalles de la diferencia entre @see y @inheritDoc

87

He revisado la referencia de JavaDoc , y aunque entiendo la diferencia básica entre @see(varios enlaces) y {@inheritDoc}(exportación del comentario de JavaDoc de la superclase), necesito una aclaración sobre cómo se implementaron realmente las cosas.

En Eclipse IDE, cuando selecciono "Generar comentarios de elementos" para el método heredado (desde la interfaz, o anulación de toString (), etc.), se crea el siguiente comentario

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

Si estoy obligado a JavaDoc producto debería dejar las cosas así, sustituir @seecon {@inheritDoc}, o convertirlo en bona fide JavaDoc como tal:

/**
 * {@inheritDoc}
 */

Y cuando hago eso, ¿debería mantener la marca del método class #?

java javadoc comments theUg
fuente

Respuestas:

142

En primer lugar, debe eliminar la plantilla de eclipse original porque es simplemente basura ruidosa. Ponga documentos significativos o no ponga nada en absoluto. Pero la repetición inútil de lo obvio usando plantillas IDE simplemente satura el código.

En segundo lugar, si usted está obligado a javadoc productos, entonces usted tiene que hacer la observación comienzo con /**. De lo contrario, no es javadoc.

Por último, si está anulando, debe usar @inheritDoc(suponiendo que desee agregar a los documentos originales, como @seh señaló en un comentario, si solo desea duplicar los documentos originales, entonces no necesita nada). @seesolo debería usarse para hacer referencia a otros métodos relacionados.

jtahlborn
fuente
75
Solo debe usarlo @inheritDocsi tiene la intención de agregar a la documentación original de la superclase. Si simplemente desea que se duplique, Javadoc ya lo hará, notando que la documentación de la superclase se aplica al método reemplazado de la subclase porque la subclase no proporcionó documentación adicional.
seh
4
Genere los documentos con y sin @inheritDocy no veo ninguna diferencia. Incluso sin el @inheritDoc, veo que el Javadoc de la clase derivada se agregó a la clase base.
randominstanceOfLivingThing
Vine aquí porque checkstyle se queja de que "el método no parece estar diseñado para la extensión". Una buena idea podría ser usar @inheritDocy luego agregar alguna documentación específica de implementación, por ejemplo, cómo implementa / sobrescribe el método principal, y especialmente POR QUÉ lo hace de la manera en que lo hace.
Ben