Я хотів би зробити один із своїх методів "застарілим" = більше не використовуватися.

Але все ж хотілося б, щоб це було в моєму API. Я просто хочу показати "попередження" всім, хто використовує цей метод.

Як я можу цього досягти?

Використовувати @Deprecatedза методом. Не забудьте про уточнення поля javadoc:

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

Використовуйте як @Deprecatedпримітку, так і @deprecatedтег JavaDoc.

@deprecatedJavaDoc тег використовується для документування.

@DeprecatedАнотації інструктує компілятор , що метод є застарілим. Ось що йдеться в документі Sun / Oracles на цю тему:

Використання @Deprecatedпримітки для зняття класу, методу чи поля гарантує, що всі компілятори видаватимуть попередження, коли код використовує цей програмний елемент. Навпаки, немає гарантії, що всі компілятори завжди видаватимуть попередження на основі @deprecatedтегу Javadoc, хоча в даний час компілятори Sun роблять це. Інші компілятори можуть не видавати таких попереджень. Таким чином, використання @Deprecatedанотації для генерації попереджень є більш портативним, що спирається на @deprecatedтег Javadoc.

Ви можете знайти повний документ у розділі Як і коли знецінити API

оскільки деякі незначні пояснення були відсутні

Використовуйте @Deprecatedпримітку про такий метод

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

не забудьте пояснити:

1. Чому цей метод більше не рекомендується . Які проблеми виникають при його використанні. Надайте посилання на дискусію з цього питання, якщо така є. (не забудьте розділити рядки для читабельності<br/>
2. Коли він буде видалений . (нехай ваші користувачі знають, наскільки вони ще можуть розраховувати на цей метод, якщо вирішили дотримуватися старого способу)
3. Надайте рішення або посилання на рекомендований метод {@link #setPurchasePrice()}

Можна зробити дві речі:

1. Додайте @Deprecatedпримітку до методу та
2. Додайте @deprecatedтег до javadoc методу

Ви повинні робити і те, і інше !

Цитуючи документацію Java на цю тему:

Починаючи з J2SE 5.0, ви застараєте клас, метод або поле, використовуючи анотацію @Deprecated. Крім того, ви можете використовувати тег @deprecated Javadoc, щоб повідомити розробникам, що використовувати замість цього.

Використання примітки змушує компілятор Java генерувати попередження, коли використовується застарілий клас, метод чи поле. Компілятор пригнічує попередження про депрекацію, якщо застарілий блок компіляції використовує застарілий клас, метод або поле. Це дозволяє створювати застарілі API без створення попереджень.

Настійно рекомендуємо використовувати тег Javadoc @deprecated з відповідними коментарями, де пояснюється, як використовувати новий API. Це гарантує, що розробники матимуть працездатний шлях міграції зі старого API до нового API

Використовуйте примітку @Deprecated для свого методу, і ви також повинні згадати її у своїх javadocs.

Погляньте на @Deprecatedанотацію.