Me gustaría hacer que uno de mis métodos quede “obsoleto” = no se use más.

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

¿Cómo puedo lograr eso?

Usar @Deprecated en 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() {
// ...
}

usa ambos @Deprecated anotación y la @deprecated Etiqueta JavaDoc.

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

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

Utilizando el @Deprecated La anotación para desaprobar una clase, un método o un campo garantiza que todos los compiladores emitan 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 el @deprecated Etiqueta Javadoc, aunque los compiladores de Sun actualmente lo hacen. Es posible que otros compiladores no emitan tales advertencias. Así, usando el @Deprecated La anotación para generar advertencias es más portátil que confiar en el @deprecated Etiqueta Javadoc.

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

ya que faltaban algunas explicaciones menores

Usar @Deprecated anotación 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 sera removido. (haga saber a sus usuarios cuánto pueden confiar en este método si deciden seguir con el método anterior)
3. Proveer una solución o enlace al método que recomiendas {@link #setPurchasePrice()}

Hay dos cosas que puedes hacer:

1. Añade el @Deprecated anotación al método, y
2. Agrega un @deprecated etiqueta al javadoc del método

Debería Haz ambos!

citando el documentación java en esta asignatura:

A partir de J2SE 5.0, se descarta una clase, un método o un campo mediante la anotación @Deprecated. Además, puede usar la etiqueta @deprecated Javadoc para decirles a los desarrolladores qué usar en su lugar.

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

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

Utilizar el anotación @Deprecated para su método, y también debe mencionarlo en sus javadocs.

Echa un vistazo a la @Deprecated anotación.