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

Но все же я хотел бы иметь это в своем 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аннотацию.