¿Cómo usar anotaciones en Kotlin?

Las anotaciones en Kotlin se utilizan para agregar metainformación a clases, propiedades, funciones, expresiones y parámetros. No realizan acciones directas, pero pueden ser utilizadas por el compilador, frameworks u otras bibliotecas para diferentes procesamientos.

Aspectos principales de uso:

1. Sintaxis: Las anotaciones se colocan antes del elemento al que se aplican, precedidas por @. Si la anotación tiene parámetros, estos se especifican entre paréntesis después del nombre.

   @Deprecated("Usa newFunction en su lugar")
   fun oldFunction() {
       // ...
   }
   
   @JvmStatic
   fun staticMethod() {
       // ...
   }
   

2. Aplicación a diferentes elementos: Las anotaciones pueden aplicarse a:

   • Clases (class):

     @Serializable
     class User(val name: String)
     

   • Propiedades (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • Funciones (fun):

     @Test
     fun testSomething() {
         // ...
     }
     

   • Parámetros de constructores/funciones:

     fun processUser(@NotNull user: User) {
         // ...
     }
     

   • Expresiones:

     fun calculate(@Ignore parameter: Int) {
         // ...
     }
     

   • Tipos (@Target(AnnotationTarget.TYPE)):

     val list: @NotNull List<String> = emptyList()
     

3. Lugares de aplicación (Use-site Targets): Para desambiguar a qué elemento exactamente se aplica la anotación, cuando hay varias (por ejemplo, campo y getter), se utilizan use-site targets.

   Target	Descripción
   @file:	Se aplica a todo el archivo
   @property:	Se aplica a la propiedad completa
   @field:	Se aplica al campo de respaldo (backing field)
   @get:	Se aplica al getter de la propiedad
   @set:	Se aplica al setter de la propiedad
   @param:	Se aplica al parámetro del constructor
   @setparam:	Se aplica al parámetro del setter de la propiedad
   @delegate:	Se aplica a la instancia de la propiedad delegada
   @receiver:	Se aplica al tipo receptor

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject se aplica al campo 'dependency'
   }
   

4. Declaración de anotaciones personalizadas: Las anotaciones propias se declaran con la palabra clave annotation class. Los parámetros de la anotación pueden ser tipos primitivos, cadenas, clases (KClass), enumeraciones, otras anotaciones o arreglos de estos tipos.

   annotation class MyAnnotation(val value: String, val count: Int = 0)
   
   @MyAnnotation("Hola", count = 5)
   class AnnotatedClass {
       // ...
   }
   

5. Meta-anotaciones: Las anotaciones pueden estar marcadas con meta-anotaciones que definen su comportamiento y aplicabilidad.

   • @Target: Indica qué elementos pueden ser anotados.
   • @Retention: Indica en qué etapa de la vida la anotación está presente (SOURCE, BINARY, RUNTIME).
   • @Repeatable: Permite aplicar la anotación varias veces al mismo elemento.
   • @MustBeDocumented: Indica que la anotación debe ser parte de la API pública generada por la herramienta de documentación.

   @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
   @Retention(AnnotationRetention.RUNTIME)
   annotation class ProcessedByFramework
   

Las anotaciones se usan ampliamente en Kotlin para integración con frameworks JVM (Spring, Android), serialización (Kotlinx.serialization), testing (JUnit) y creación de bibliotecas propias basadas en metainformación.