Come deprecare un metodo

Quando si vuole eliminare un metodo da una classe, evitando di interferire sul codice che da questa dipende, la soluzione sta nella deprecazione.
Dalla versione 1.5 di Java per deprecare un metodo si deve usare l'annotazione @Deprecated, che può essere usata sulle classi, sui metodi o sui campi.
E' buona norma accompagnare l'annotazione con i javadoc, usando il tag @deprecated nel cui testo è opportuno specificare perchè il metodo viene deprecato e qual è l'alternativa da utilizzare.

    /**
     * [...]
     * @deprecated use {@link #importTrade(Trade)} instead ...
     */
    @Deprecated
    Long importTradeFromXML(String xml) {
      ...

Per creare nei javadoc un collegamento ad un altro metodo viene utilizzato il tag @link la cui sintassi è:

{@link  package.class#member  label} 

Nel caso di overloading dei metodi si deve specificare il metodo facendo seguire al nome l'elenco dei tipi degli argomenti presi in ingresso.

Vedi anche:
How and When To Deprecate APIs
javadoc @deprecated
javadoc @link