Me gustaría hacer que uno de mis métodos sea "obsoleto" = ya no se usa.

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

¿Cómo puedo lograr eso?

Uso @Deprecateden 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() {
// ...
}

Utilice tanto la @Deprecatedanotación como la@deprecated etiqueta JavaDoc.

los @deprecated etiqueta JavaDoc se utiliza con fines de documentación.

La @Deprecatedanotación indica al compilador que el método está en desuso. Esto es lo que dice en el documento Sun / Oracles sobre el tema:

Usar la @Deprecatedanotación 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. Por el contrario, no hay garantía de que todos los compiladores siempre emitan advertencias basadas en la @deprecatedetiqueta Javadoc, aunque los compiladores de Sun actualmente lo hacen. Otros compiladores no pueden emitir tales advertencias. Por lo tanto, usar la @Deprecatedanotación para generar advertencias es más portátil que confiar en la @deprecatedetiqueta Javadoc.

Puede encontrar el documento completo en Cómo y cuándo desaprobar las API

ya que faltaban algunas explicaciones menores

Use @Deprecatedanotaciones 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:

1. ¿Por qué ya no se recomienda este método ? Qué problemas surgen al usarlo. Proporcione un enlace a la discusión sobre el asunto, si corresponde. (recuerde separar las líneas para facilitar la lectura<br/>
2. Cuando será removido . (deje que sus usuarios sepan cuánto pueden confiar en este método si deciden seguir el viejo método)
3. Proporcione una solución o enlace al método que recomienda. {@link #setPurchasePrice()}

Hay dos cosas que puedes hacer:

1. Añade el @Deprecated anotación al método y
2. Agregue una @deprecatedetiqueta al javadoc del método

¡Deberías hacer las dos cosas !

Citando la documentación de Java sobre este tema:

Comenzando con J2SE 5.0, desaprueba una clase, método o campo utilizando la anotación @Deprecated. Además, puede usar la etiqueta @doc obsoleta de Javadoc para indicar 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 desaprobada usa una clase, un método o un campo desaprobados. Esto le permite crear API heredadas sin generar advertencias.

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

Use la anotación @Deprecated para su método, y también debe mencionarla en sus javadocs.

Echa un vistazo a la @Deprecatedanotación.