When code evolves we usually deprecate old code. Sometimes we come across deprecations without any hints with what to replace it with. Kotlin has a solution for this by allowing you to specify a replace instruction.

For example, we created have an old REST client.

package com.company.clients.ancient

interface OldRestClient {
    @GET("/posts/{id}")
    fun post(@Path("id") id: Int): Call<PostDto>

    @GET("/todos/{id}")
    fun todo(@Path("id") id: Int): Call<TodoDto>
}

And we want to replace it with a new REST client:

package com.company.clients.new

interface NewRestClient {
    @GET("/posts/{id}")
    suspend fun post(@Path("id") id: Int): PostDto

    @GET("/todos/{id}")
    suspend fun todo(@Path("id") id: Int): TodoDto
}

We can now mark the old rest client with a Deprecated annotation and specify how to replace it, including the new set of required imports!

package com.company.clients.ancient
@Deprecated(message = "Use the new client that follows our standards", replaceWith = ReplaceWith(
    expression = "NewRestClient",
    imports = ["com.company.clients.new.NewRestClient"]
))
interface OldRestClient {
    @GET("/posts/{id}")
    fun post(@Path("id") id: Int): Call<PostDto>

    @GET("/todos/{id}")
    fun todo(@Path("id") id: Int): Call<TodoDto>
}

Your IDE can now suggest the replacement and insert the required imports automatically:

Suggestions by IDEA

Tested with Kotlin 1.4.10

shadow-left