usar - generar documentacion de codigo java

¿Cómo declarar o marcar un método Java como obsoleto?

Question

Me gustaría que uno de mis métodos "en desuso" = no se use más.

Pero aun así me gustaría tenerlo en mi API. Solo quiero mostrar "advertencias" a cualquiera que use ese método.

¿Cómo puedo lograr eso?

Answer 1

Echa un vistazo a la anotación @Deprecated .

Answer 2

Hay dos cosas que puedes hacer:

1. Agregue la anotación @Deprecated al método, y
2. Agregue una etiqueta @deprecated al javadoc del método

Deberías hacer ambas cosas !

Citando la documentación de java sobre este tema:

A partir de J2SE 5.0, puede desaprobar una clase, un método o un campo utilizando la anotación @Deprecated. Además, puede usar la etiqueta Javadoc dedeprecated y decirle a los desarrolladores qué usar en su lugar.

El uso de la anotación hace que el compilador de Java genere advertencias cuando se utiliza la clase, el método o el campo en desuso. El compilador suprime las advertencias de desaprobación si una unidad de compilación en desuso usa una clase, método o campo desaprobado. Esto le permite crear API heredadas sin generar advertencias.

Se recomienda encarecidamente que use la etiqueta Javadoc @deprecated con los comentarios apropiados que expliquen cómo usar la nueva API. Esto asegura que los desarrolladores tendrán una ruta de migración viable desde la API antigua a la nueva API

Answer 3

Use la annotation @Deprecated para su método, y también debe mencionarlo en sus javadocs.

Answer 4

Use tanto la anotación @Deprecated como la etiqueta @deprecated .

La etiqueta de @deprecated se utiliza para fines de documentación.

La anotación @Deprecated indica al compilador que el método está en desuso. Aquí está lo que dice el documento de Sun / Oracles sobre el tema:

El uso de la anotación @Deprecated para desaprobar una clase, método o campo asegura que todos los compiladores emitirán advertencias cuando el código use ese elemento del programa. En contraste, no hay garantía de que todos los compiladores siempre emitan advertencias basadas en la etiqueta Javadoc @deprecated , aunque los compiladores de Sun actualmente lo hacen. Otros compiladores no pueden emitir tales advertencias. Por lo tanto, usar la anotación @Deprecated para generar advertencias es más portátil que confiar en la etiqueta Javadoc de @deprecated .

Puede encontrar el documento completo en docs.oracle.com/javase/1.5.0/docs/guide/javadoc/deprecation/…

Answer 5

ya que faltaban algunas explicaciones menores

Utilice la anotación @Deprecated en el método como este

/**
 * @param baseprice
 * 
 * @deprecated  reason this method is deprecated </br>
 *              {will be removed in next version} </br>
 *              use {@link #setPurchasePrice()} instead like this: 
 * 
 * <blockquote>
 * <pre>
 * getProduct().setPurchasePrice(200) 
 * </pre></blockquote>
 * 
 */
@Deprecated
public void setBaseprice(int baseprice) {
}

recuerda explicar:

• Por qué ya no se recomienda este método, recuerde que debe separarse de la línea para facilitar la lectura </br>
• Cuándo se eliminará (infórmeles a los usuarios cuánto pueden confiar en este método si decidieron seguir el método anterior)
• Proporcione una solución o enlace al método que recomienda {@link #setPurchasePrice()}

Answer 6

Utilice @Deprecated en el método. No te olvides de aclarar el campo javadoc:

/**
 * Does some thing in old style.
 *
 * @deprecated use {@link #new()} instead.  
 */
@Deprecated
public void old() {
// ...
}