¿Cómo documentar un método que anula otro método?

Question

Siempre me pregunté cómo documentar un método que anula un mensaje de una clase base. Normalmente agrego un documento de Java a cada método público y a algunos métodos privados y protegidos.

Pero autogenerating un bloque de documentación para un método de reemplazo en Eclipse produce algo como esto:

/* 
* (non-Javadoc) 
* 
* @see javax.swing.JComponent#paintComponent(java.awt.Graphics) 
*/ 

¿Es esta una buena manera de documentar la anulación? ¿Debo heredar/copiar la documentación de la clase base?

¿Qué estás haciendo como documentación para este caso especial? Me gustaría tener una visión general de las prácticas que se utilizan.

Answer 1

Todos los métodos, público privado y protegido, deben estar documentados describiendo lo que hace. Olvídese de heredar documentación de una clase base; puede incluir un enlace si lo desea, pero mientras exista información que anule un método heredado, la otra persona podrá buscarlo por sí misma. SECO - no te repitas: documenta el método de la clase base en un solo lugar.

Ni siquiera creo que sea bueno documentar qué método reemplaza, porque eso puede cambiar y será difícil mantenerlo actualizado si inserta nuevas clases en la jerarquía entre su clase y la clase base . Simplemente la información que anula un método heredado es suficiente.

Si sus métodos son demasiado complejos para documentarlos en unas pocas líneas de comentarios, entonces probablemente sean demasiado complejos y deberían ser refactorizados.

Answer 2

incluyendo la anotación @Override debería ser suficiente para enviar un curioso desarrollador al super.