Ako používať anotácie v Kotlin?

Anotácie v Kotlin sa používajú na pridanie meta-informácií ku triedam, vlastnostiam, funkciám, výrazom a parametrom. Nevykonávajú priamu akciu, ale môžu byť použité prekladačom, rámcami alebo inými knižnicami na rôzne spracovania.

Hlavné aspekty použitia:

Syntax: Anotácie sa uvádzajú pred prvkom, ku ktorému sa vzťahujú, v hranatých zátvorkách @. Ak anotácia má parametre, sú uvedené v zátvorkách za názvom.
```
@Deprecated("Use newFunction instead")
fun oldFunction() {
    // ...
}

@JvmStatic
fun staticMethod() {
    // ...
}
```

Použitie na rôzne prvky: Anotácie môžu byť aplikované na:

Triedy (class):

@Serializable
class User(val name: String)

Vlastnosti (val, var):

@Inject
lateinit var userRepository: UserRepository

Funkcie (fun):

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

Parametre konštruktorov/funkcií:

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

Výrazy:

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

Typy (@Target(AnnotationTarget.TYPE)):

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

Miesta použitia (Use-site Targets): Na disambiguáciu toho, ku ktorému prvku sa anotácia vzťahuje, keď ich je viac (napríklad pole a getter), sa používajú use-site targets.

Target	Popis
`@file:`	Vzťahuje sa na celý súbor
`@property:`	Vzťahuje sa na celú vlastnosť
`@field:`	Vzťahuje sa na backing field
`@get:`	Vzťahuje sa na getter vlastnosti
`@set:`	Vzťahuje sa na setter vlastnosti
`@param:`	Vzťahuje sa na parameter konštruktora alebo funkcie
`@setparam:`	Vzťahuje sa na parameter settera
`@delegate:`	Vzťahuje sa na inštanciu delegovanej vlastnosti
`@receiver:`	Vzťahuje sa na typ príjemcu

class Example(@field:Inject val dependency: Dependency) {
    // @field:Inject sa vzťahuje na pole 'dependency'
}

Vytváranie vlastných anotácií: Vlastné anotácie sa deklarujú kľúčovým slovom annotation class. Parametre anotácie môžu byť primitívne typy, reťazce, triedy (KClass), enumy, iné anotácie alebo pole týchto typov.
```
annotation class MyAnnotation(val value: String, val count: Int = 0)

@MyAnnotation("Hello", count = 5)
class AnnotatedClass {
    // ...
}
```
Meta-anotácie: Anotácie môžu byť označené meta-anotáciami, ktoré určujú ich správanie a použiteľnosť.
- @Target: Uvádza, ktoré prvky môžu byť anotované.
- @Retention: Uvádza, v ktorej fáze životného cyklu je anotácia prítomná (SOURCE, BINARY, RUNTIME).
- @Repeatable: Umožňuje opakované použitie anotácie na rovnakom prvku.
- @MustBeDocumented: Uvádza, že anotácia by mala byť súčasťou verejného API, ktoré generujú nástroje na dokumentáciu.
```
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class ProcessedByFramework
```

Anotácie sú široko používané v Kotlin-e na integráciu s JVM rámcami (Spring, Android), serializáciu (Kotlinx.serialization), testovanie (JUnit) a tvorbu vlastných knižníc založených na meta-informáciách.