Je voudrais rendre une de mes méthodes "obsolète" = plus utilisée.

Mais j'aimerais quand même l'avoir dans mon API. Je veux juste montrer un "avertissement" à toute personne utilisant cette méthode.

Comment puis-je y parvenir?

Utilisez la @Deprecatedméthode. N'oubliez pas de clarifier le champ javadoc:

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

Utilisez à la fois l' @Deprecatedannotation et la @deprecatedbalise JavaDoc.

La @deprecatedbalise JavaDoc est utilisée à des fins de documentation.

L' @Deprecatedannotation indique au compilateur que la méthode est obsolète. Voici ce qu'il dit dans le document Sun / Oracles sur le sujet:

L'utilisation de l' @Deprecatedannotation pour déprécier une classe, une méthode ou un champ garantit que tous les compilateurs émettront des avertissements lorsque le code utilise cet élément de programme. En revanche, rien ne garantit que tous les compilateurs émettront toujours des avertissements basés sur la @deprecatedbalise Javadoc, bien que les compilateurs Sun le fassent actuellement. D'autres compilateurs peuvent ne pas émettre de tels avertissements. Ainsi, l'utilisation de l' @Deprecatedannotation pour générer des avertissements est plus portable que l'utilisation de la @deprecatedbalise Javadoc.

Vous pouvez trouver le document complet sur Comment et quand déprécier les API

car il manquait quelques explications mineures

Utilisez une @Deprecatedannotation sur la méthode comme celle-ci

 /**
 * @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) {
}

n'oubliez pas d'expliquer:

1. Pourquoi cette méthode n'est plus recommandée . Quels problèmes surviennent lors de son utilisation. Fournissez un lien vers la discussion sur la question, le cas échéant. (n'oubliez pas de séparer les lignes pour plus de lisibilité<br/>
2. Quand il sera supprimé . (faites savoir à vos utilisateurs combien ils peuvent encore compter sur cette méthode s'ils décident de s'en tenir à l'ancienne méthode)
3. Fournissez une solution ou un lien vers la méthode que vous recommandez {@link #setPurchasePrice()}

Il y a deux choses que tu peux faire:

1. Ajoutez l' @Deprecatedannotation à la méthode et
2. Ajouter une @deprecatedbalise au javadoc de la méthode

Vous devriez faire les deux !

Citant la documentation java sur ce sujet:

À partir de J2SE 5.0, vous déconseillez une classe, une méthode ou un champ à l'aide de l'annotation @Deprecated. De plus, vous pouvez utiliser la balise Javadoc @deprecated pour indiquer aux développeurs ce qu'il faut utiliser à la place.

L'utilisation de l'annotation oblige le compilateur Java à générer des avertissements lorsque la classe, la méthode ou le champ obsolète est utilisé. Le compilateur supprime les avertissements de dépréciation si une unité de compilation déconseillée utilise une classe, une méthode ou un champ déconseillé. Cela vous permet de créer des API héritées sans générer d'avertissements.

Il est fortement recommandé d'utiliser la balise Javadoc @deprecated avec des commentaires appropriés expliquant comment utiliser la nouvelle API. Cela garantit que les développeurs auront un chemin de migration réalisable de l'ancienne API vers la nouvelle API

Utilisez l' annotation @Deprecated pour votre méthode et vous devez également la mentionner dans vos javadocs.

Jetez un œil à l' @Deprecatedannotation.