Una cosa muy interesante de Kotlin es la anotación <code class="highlighter-rouge">@Deprecated, que lejos de notificar al usuario que una funcionalidad está deprecada y se desaconseja su uso, nos permite automatizar la migración del código.

Y aunque nuestra intención sea hacer el cambio directamente y no mantener el código deprecado, esta anotación nos permitirá **ahorrarnos mucho trabajo **haciendo dicha migración. Pues está integrada con intelliJ y permite hacer la migración automáticamente de una característica deprecada o de todas a la vez.

El problema:

Partiendo de este fragmento de código:

Supongamos que ahora nos interesa que getResults en vez de devolver una lista de enteros devuelva un objeto <code class="highlighter-rouge">Result que ademeás de la lista contiene más información. Pero no queremos cambiar, de momento, todos los sitios en los que se utiliza este método.

Ahora tenemos que todos los sitios en los que se llamaba a getResults, se han roto. Con lo que en vez de hacer esto, creamos otro método que es el que devuelve el resultado complejo, y mantenemos el método con el comportamiento antiguo:

Ahora lo que queremos es que se deje de utilizar el getResults antiguo, y que todos los sitios donde se llama a <code class="highlighter-rouge">getResults() de momento se reemplacen por <code class="highlighter-rouge">getResults().list, al menos de momento.

Aquí es donde entra en acción la anotación <code class="highlighter-rouge">@Deprecated y su replaceWith.

Utilizando @Deprecated

Vamos a añadir la anotación <code class="highlighter-rouge">@Deprecated.
En su versión más básica, acepta un único argumento con un mensaje descriptivo sobre por qué se depreca o cómo avanzar.
Y en su versión más potente disponemos de dos argumentos adicionales.
Dichos argumentos nos permiten automatizar la migración, y elegir el comportamiento ante el uso: no compilar, warning, aviso.

En este código instamos a utilizar getFullResults en lugar de getResults, proporcionamos un reemplazo automático (que podría incluir this, argumentos o incluso añadir imports adicionales).
Además indicamos a Kotlin que no permita compilar el código hasta que no se realice la migración.

Si nos colocamos encima de las llamadas a getResults, nos encontramos con el mensaje que hemos escrito.
Y además un quickfix nos permite cambiar cada caso individualmente de forma automátizada utilizando el patrón definido en replaceWith, así como otro quickfix para hacer dicho reemplazo en todas las llamadas a getResults.

Si tenemos varios <code class="highlighter-rouge">@Deprecated.

En el menú <code class="highlighter-rouge">Analyze, disponemos de <code class="highlighter-rouge">Code Cleanup... que nos permite hacer limpieza de todo el código incluyendo, organización de imports el reemplazo automático de todos los <code class="highlighter-rouge">@Deprecated con replaceWith que sigan referenciados.

<code class="highlighter-rouge">getResults ahora se queda marcado en gris sin referencias y ya podemos eliminarlo de forma segura (por ejemplo con alt+enter y el quick fix<code class="highlighter-rouge">Safe Delete...).

Ejemplo más complejo:

Con ReplaceWith, podemos desde cambiar el orden de los parámetros, acceder a this, añadir accesos adicionales, modificar un argumento aplicándole transformaciones u otros cambios que se nos ocurran:

Code Cleanup…

Informe de deprecación

Quickfix

Borrar de forma segura