metodo - ¿Debo usar JavaDoc deprecation o la anotación en Java?
javadoc wiki (5)
De la boca del caballo :
NOTA: La Especificación del lenguaje Java requiere que los compiladores emitan advertencias cuando se usan clases, métodos o campos marcados con la anotación @Deprecated. La Especificación del lenguaje Java no exige a los compiladores que emitan advertencias cuando se accede a clases, métodos o campos marcados con la etiqueta @deprecated Javadoc, aunque los compiladores de Sun actualmente lo hacen.
Entonces, básicamente, si quieres una garantía de que habrá advertencias del compilador, debes usar la anotación. Y debido a la impresionante incompetencia de algunos diseñadores de API, necesita especificar también la etiqueta javadoc para dar una explicación.
Personalmente, diría que la anotación es inútil y debería omitirse hasta que se solucione, ya que cualquier buen compilador o IDE mostrará advertencias con la etiqueta javadoc también.
En este momento, hay dos formas de marcar código como depreacted en java.
A través de JavaDoc
/**
* @deprecated
*/
O como una anotación:
@Deprecated
Este es mi problema: me parece demasiado declarar ambos cuando marque un método como obsoleto al usar Eclipse. Realmente solo quiero usar uno de ellos.
Sin embargo, ¿el uso de la anotación proporciona al compilador información útil adicional?
Pero solo usando la anotación, no puedo decir por qué el método está en desuso: solo puedo hacer eso con JavaDoc, y desaprobar un método sin tener en cuenta por qué es malo.
Entonces, ¿puedo usar solo uno de ellos? ¿O debería aprender a especificar ambos?
Deberías escribir ambos. La anotación @Deprecated es para el compilador y la etiqueta @deprecated JavaDoc es para la persona que desea saber ahora por qué está obsoleto.
Un ejemplo puede verse así:
/**
* @deprecated We dont need this Method because ...
*/
@Deprecated
public void doStuff(){..}
Deberías usar ambos. La anotación permite que el compilador muestre una advertencia cada vez que se usa un método en desuso, y el javadoc explica por qué. Ambos son importantes.
Según el tutorial de Java Annotations de Oracle:
Cuando un elemento está en desuso, también debe documentarse utilizando la etiqueta @deprecated de Javadoc ...
Debes especificar ambos.
La anotación le permite al compilador conocerlo y desencadenar advertencias cuando se usa el método. El atributo JavaDoc les informa a los desarrolladores antes de que comiencen a usarlo.
¡Estas son dos cosas muy diferentes!
Esto se puede resolver fácilmente con un buen IDE.
Eclipse Neon, por ej. agrega automáticamente la anotación @Deprecated, cuando creo un javadoc @deprecated en un método o campo.
Así que simplemente escribo el javadoc con la explicación adecuada y dejo que el IDE se encargue de agregar la anotación @Deprecated, en el momento en que guardo el archivo.