Use @Deprecated on method. Don't forget about clarifying javadoc field:

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

Use both @Deprecated annotation and the @deprecated JavaDoc tag.

The @deprecated JavaDoc tag is used for documentation purposes.

The @Deprecated annotation instructs the compiler that the method is deprecated. Here is what it says in Sun/Oracles document on the subject:

Using the @Deprecated annotation to deprecate a class, method, or field ensures that all compilers will issue warnings when code uses that program element. In contrast, there is no guarantee that all compilers will always issue warnings based on the @deprecated Javadoc tag, though the Sun compilers currently do so. Other compilers may not issue such warnings. Thus, using the @Deprecated annotation to generate warnings is more portable that relying on the @deprecated Javadoc tag.

You can find the full document at How and When to Deprecate APIs

since some minor explanations were missing

Use @Deprecated annotation on the method like this

 /** * @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> *  */@Deprecatedpublic void setBaseprice(int basePrice) {}

remember to explain:

1. Why is this method no longer recommended. What problems arise when using it. Provide a link to the discussion on the matter if any. (remember to separate lines for readability <br/>
2. When it will be removed. (let your users know how much they can still rely on this method if they decide to stick to the old way)
3. Provide a solution or link to the method you recommend {@link #setPurchasePrice()}