Jak používat anotace v Kotlinu?

Anotace v Kotlinu se používají k přidání meta-informací ke třídám, vlastnostem, funkcím, výrazům a parametrům. Nevykonávají přímou akci, ale mohou být použity kompilátorem, rámci nebo jinými knihovnami pro různé zpracování.

Hlavní aspekty použití:

Syntaxe: Anotace se uvádějí před prvkem, ke kterému se vztahují, v hranatých závorkách @. Pokud má anotace parametry, jsou uvedeny v závorkách za názvem.
```
@Deprecated("Use newFunction instead")
fun oldFunction() {
    // ...
}

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

Použití na různé prvky: Anotace lze použít na:

Třídy (class):

@Serializable
class User(val name: String)

Vlastnosti (val, var):

@Inject
lateinit var userRepository: UserRepository

Funkce (fun):

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

Parametry konstruktorů/funkcí:

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

Výrazy:

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

Typy (@Target(AnnotationTarget.TYPE)):

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

Místa použití (Use-site Targets): Pro disambiguaci toho, ke kterému prvku se anotace vztahuje, když jich je více (například pole a getter), se používají use-site targets.

Target	Popis
`@file:`	Vztahuje se na celý soubor
`@property:`	Vztahuje se na celou vlastnost
`@field:`	Vztahuje se k backing fieldu
`@get:`	Vztahuje se k getteru vlastnosti
`@set:`	Vztahuje se k setteru vlastnosti
`@param:`	Vztahuje se k parametru konstruktoru nebo funkce
`@setparam:`	Vztahuje se k parametru setteru
`@delegate:`	Vztahuje se k instanci delegované vlastnosti
`@receiver:`	Vztahuje se k typu příjemce

class Example(@field:Inject val dependency: Dependency) {
    // @field:Inject se vztahuje na pole 'dependency'
}

Vytváření vlastních anotací: Vlastní anotace se deklarují klíčovým slovem annotation class. Parametry anotace mohou být primitivními typy, řetězci, třídami (KClass), enumy, jinými anotacemi nebo poli těchto typů.
```
annotation class MyAnnotation(val value: String, val count: Int = 0)

@MyAnnotation("Hello", count = 5)
class AnnotatedClass {
    // ...
}
```
Meta-anotace: Anotace mohou být označeny meta-anotacemi, které určují jejich chování a použitelnost.
- @Target: Určuje, které prvky mohou být anotovány.
- @Retention: Určuje, v jaké fázi životního cyklu je anotace přítomna (SOURCE, BINARY, RUNTIME).
- @Repeatable: Umožňuje opakované použití anotace na stejném prvku.
- @MustBeDocumented: Určuje, že anotace by měla být součástí veřejného API generovaného dokumentačními nástroji.
```
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class ProcessedByFramework
```

Anotace jsou široce používány v Kotlinu pro integraci s JVM frameworky (Spring, Android), serializaci (Kotlinx.serialization), testování (JUnit) a tvorbu vlastních knihoven založených na meta-informacích.