Gostaria de tornar um dos meus métodos "obsoleto" = não usado mais.

Mas ainda assim eu gostaria de tê-lo na minha API. Eu só quero mostrar "aviso" para quem usa esse método.

Como posso conseguir isso?

Use @Deprecatedno método Não se esqueça de esclarecer o campo javadoc:

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

Use a @Deprecatedanotação e a @deprecatedtag JavaDoc.

A @deprecatedtag JavaDoc é usada para fins de documentação.

A @Deprecatedanotação instrui o compilador que o método está obsoleto. Aqui está o que diz o documento Sun / Oracles sobre o assunto:

O uso da @Deprecatedanotação para reprovar uma classe, método ou campo garante que todos os compiladores emitam avisos quando o código usar esse elemento do programa. Por outro lado, não há garantia de que todos os compiladores sempre emitam avisos com base na @deprecatedtag Javadoc, embora atualmente os compiladores da Sun o façam. Outros compiladores podem não emitir esses avisos. Portanto, usar a @Deprecatedanotação para gerar avisos é mais portátil do que confiar na @deprecatedtag Javadoc.

Você pode encontrar o documento completo em Como e quando descontinuar APIs

pois faltavam algumas explicações menores

Use @Deprecatedanotação no 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) {
}

lembre-se de explicar:

1. Por que esse método não é mais recomendado . Que problemas surgem ao usá-lo. Forneça um link para a discussão sobre o assunto, se houver. (lembre-se de separar linhas para facilitar a leitura<br/>
2. Quando será removido . (informe aos usuários o quanto eles ainda podem confiar nesse método se decidirem seguir o caminho antigo)
3. Forneça uma solução ou link para o método recomendado {@link #setPurchasePrice()}

Há duas coisas que você pode fazer:

1. Adicione a @Deprecatedanotação ao método e
2. Adicione uma @deprecatedtag ao javadoc do método

Você deve fazer as duas coisas !

Citando o documentação java sobre este assunto:

A partir do J2SE 5.0, você preteriu uma classe, método ou campo usando a anotação @Deprecated. Além disso, você pode usar a tag Javadoc @ obsoleta para informar aos desenvolvedores o que usar.

O uso da anotação faz com que o compilador Java gere avisos quando a classe, método ou campo descontinuado é usado. O compilador suprime avisos de descontinuação se uma unidade de compilação descontinuada usar uma classe, método ou campo descontinuado. Isso permite criar APIs herdadas sem gerar avisos.

É altamente recomendável usar a tag Javadoc @ obsoleta com comentários apropriados explicando como usar a nova API. Isso garante que os desenvolvedores tenham um caminho de migração viável da API antiga para a nova API

Use a anotação @Deprecated para seu método e você também deve mencioná-la em seus javadocs.

Dê uma olhada na @Deprecatedanotação.