Kotlin-də şərhlər necə istifadə olunur?

Kotlin-də anotasiya istifadə olunur ki, siniflərə, xüsusiyyətlərə, funksiyalara, ifadələrə və parametrlərə meta-məlumat əlavə edilsin. Onlar birbaşa fəaliyyət göstərmir, lakin tərtibçi, çərçivələr və ya digər kitabxanalar tərəfindən müxtəlif emal üçün istifadə oluna bilər.

İstifadənin əsas aspektləri:

1. Sintaksis: Anotasiya elementin əvvəlində, künc mötərizələrdə @ ilə qeyd olunur. Əgər anotasiya parametrə malikdirsə, onlar adın ardınca mötərizədə göstərilir.

   @Deprecated("Use newFunction instead")
   fun oldFunction() {
       // ...
   }
   
   @JvmStatic
   fun staticMethod() {
       // ...
   }
   

2. Fərqli elementlərə tətbiq: Anotasiya aşağıdakı elementlərə tətbiq oluna bilər:

   • Siniflər (class):

     @Serializable
     class User(val name: String)
     

   • Xüsusiyyətlər (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • Funksiyalar (fun):

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

   • Konstruktor və ya funksiya parametrləri:

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

   • İfadələr:

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

   • Növlər (@Target(AnnotationTarget.TYPE)):

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

3. İstifadə yerləri (Use-site Targets): Anotasiya hansı elementə tətbiq olunduğunu ayırd etmək üçün, xüsusən bir neçə elementə (məsələn, sahə və getter) tətbiq olunduqda, use-site targets istifadə olunur.

   Target	Təsviri
   @file:	Bütün fayla tətbiq olunur
   @property:	Xüsusiyyətə tam tətbiq olunur
   @field:	Backing field-ə tətbiq olunur
   @get:	Xüsusiyyətin getter-ə tətbiq olunur
   @set:	Xüsusiyyətin setter-ə tətbiq olunur
   @param:	Konstruktor və ya funksiya parametrinə tətbiq olunur
   @setparam:	Setter parametrinə tətbiq olunur
   @delegate:	Delegasiya olunan xüsusiyyətin nümunəsinə tətbiq olunur
   @receiver:	Qəbuledici tipə tətbiq olunur

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject 'dependency' sahəsinə tətbiq olunur
   }
   

4. İstifadəçi anotasiya elanları: Öz anotasiya elanları annotation class açar sözü ilə edilir. Anotasiya parametrləri primitiv tiplər, sətirlər, siniflər (KClass), enum-lər, digər anotasiya və ya bu tiplərin massivləri ola bilər.

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

5. Meta-anotasiya: Anotasiya onların davranışını və tətbiq sahəsini müəyyən edən meta-anotasiya ilə işarələnə bilər.

   • @Target: Hansı elementlərin anotasiya edilə biləcəyini göstərir.
   • @Retention: Anotasiya hansı mərhələdə mövcud olacağını göstərir (SOURCE, BINARY, RUNTIME).
   • @Repeatable: Eyni elementə bir neçə dəfə tətbiq olunmasına imkan verir.
   • @MustBeDocumented: Anotasiya sənədləşdirmə alətləri tərəfindən sənədləşdirilən API-nin bir hissəsi olmalıdır.

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

Anotasiya Kotlin-də JVM çərçivələri (Spring, Android), serializasiya (Kotlinx.serialization), testlər (JUnit) və öz kitabxanalarının yaradılması üçün geniş istifadə olunur, meta-məlumat əsasında.