Chciałbym, aby jedna z moich metod była „przestarzała” = już nie używana.

Ale nadal chciałbym mieć to w moim API. Chcę tylko pokazać „ostrzeżenie” każdemu, kto używa tej metody.

Jak mogę to osiągnąć?

Użyj @Deprecatedwedług metody. Nie zapomnij o wyjaśnieniu pola javadoc:

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

Użyj zarówno @Deprecatedadnotacji, jak i @deprecatedznacznika JavaDoc.

Znacznik @deprecatedJavaDoc służy do celów dokumentacji.

@DeprecatedAdnotacja instruuje kompilator, że metoda jest przestarzała. Oto, co napisano w dokumencie Sun / Oracles na ten temat:

Wykorzystanie @Deprecatedadnotacji do wycofania klasy, metody lub pola gwarantuje, że wszystkie kompilatory będą wydawały ostrzeżenia, gdy kod użyje tego elementu programu. W przeciwieństwie do tego, nie ma gwarancji, że wszystkie kompilatory zawsze będą generowały ostrzeżenia na podstawie @deprecatedznacznika Javadoc, chociaż obecnie kompilatory Sun to robią. Inne kompilatory mogą nie wydawać takich ostrzeżeń. Tak więc używanie @Deprecatedadnotacji do generowania ostrzeżeń jest bardziej przenośne niż poleganie na @deprecatedznaczniku Javadoc.

Pełen dokument można znaleźć w temacie Jak i kiedy wycofywać interfejsy API

ponieważ brakowało kilku drobnych wyjaśnień

Użyj @Deprecatedadnotacji na takiej metodzie

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

pamiętaj, aby wyjaśnić:

1. Dlaczego ta metoda nie jest już zalecana . Jakie problemy pojawiają się podczas korzystania z niego. Podaj link do dyskusji na ten temat, jeśli istnieje. (pamiętaj, aby oddzielić linie dla czytelności<br/>
2. Kiedy zostanie usunięty . (poinformuj użytkowników, na ile mogą nadal polegać na tej metodzie, jeśli zdecydują się trzymać starej metody)
3. Podaj rozwiązanie lub link do zalecanej metody {@link #setPurchasePrice()}

Możesz zrobić dwie rzeczy:

1. Dodaj @Deprecatedadnotację do metody i
2. Dodaj @deprecatedznacznik do javadoc metody

Powinieneś zrobić oba !

Cytując dokumentację Java na ten temat:

Począwszy od J2SE 5.0, klasa, metoda lub pole są przestarzałe przy użyciu adnotacji @Deprecated. Ponadto można użyć tagu Javadoc @deprecated informującego programistów, czego należy użyć.

Użycie adnotacji powoduje, że kompilator Java generuje ostrzeżenia, gdy używana jest przestarzała klasa, metoda lub pole. Kompilator eliminuje ostrzeżenia o wycofaniu, jeśli przestarzała jednostka kompilacyjna używa przestarzałej klasy, metody lub pola. Umożliwia to tworzenie starszych interfejsów API bez generowania ostrzeżeń.

Zdecydowanie zalecamy użycie tagu Javadoc @deprecated z odpowiednimi komentarzami wyjaśniającymi, jak korzystać z nowego interfejsu API. Dzięki temu programiści będą mieli wykonalną ścieżkę migracji ze starego interfejsu API do nowego interfejsu API

Użyj adnotacji @Deprecated dla swojej metody i powinieneś również wspomnieć o niej w javadocs.

Spójrz na @Deprecatedadnotację.