Ինչպես օգտագործել նշումներ Kotlin-ում?

Կոտլինում անոտացիաները օգտագործվում են մետա-տեղեկատվություն ավելացնելու համար դասականների, հատկությունների, ֆունկցիաների, արտահայտությունների և պարամետրերի համար: Դրանք չեն կատարում ուղղակի գործողություն, բայց կարող են օգտագործվել կոմպիլյատորով, ֆրեյմվորկներով կամ այլ գրադարաններով տարբեր մշակման համար:

Հիմնական օգտագործման կողմերը:

1. Սինտաքսիս: Անոտացիաները նշվում են այն տարրից առաջ, որի վրա դրանք կիրառվում են, անկյունագծային փակագծերով @. Եթե անոտացիան ունի պարամետրեր, դրանք նշվում են անունից հետո փակագծերում:

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

2. Կիրառում տարբեր տարրերի վրա: Անոտացիաները կարող են կիրառվել:

   • Դասակների (class):

     @Serializable
     class User(val name: String)
     

   • Գույքներին (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • Ֆունկցիաներին (fun):

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

   • Կոնստրուկտորների/ֆունկցիաների պարամետրերին:

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

   • արտահայտություններին:

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

   • Տիպերին (@Target(AnnotationTarget.TYPE)):

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

3. Օգտագործման վայրեր (Use-site Targets): Որպես disambiguation այն տարրին, որի վրա կիրառվում է անոտացիան, երբ դրանք մի քանի են (օրինակ, դաշտ և getter), օգտագործվում են use-site targets:

   Target	Նկարագրություն
   @file:	Կիրառվում է ամբողջ ֆայլի վրա
   @property:	Կիրառվում է ամբողջ հատկության վրա
   @field:	Կիրառվում է բեկինգ դաշտին (backing field)
   @get:	Կիրառվում է հատկության getter-ին
   @set:	Կիրառվում է հատկության setter-ին
   @param:	Կիրառվում է կոնստրուկտորի/ֆունկցիայի պարամետրի վրա
   @setparam:	Կիրառվում է հատկության setter պարամետրի վրա
   @delegate:	Կիրառվում է դելեգատացված հատկության ինստանսին
   @receiver:	Կիրառվում է ստացող տիպին

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject կիրառվում է 'dependency' դաշտին
   }
   

4. Հաճախորդական անոտացիաների հայտարարում: Անհատական անոտացիաները հայտարարում են annotation class բանալիով: Անոտացիայի պարամետրերը կարող են լինել պրիմիտիվ տիպեր, տողեր, դասեր (KClass), ցուցակներ, այլ անոտացիաներ կամ դրանց զանգվածներ:

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

5. Մետա-անոտացիաներ: Անոտացիաները կարող են նշվել մետա-անոտացիաներով, որոնք որոշում են դրանց վարքագիծը և կիրառելիությունը:

   • @Target: Նշում է, թե որ տարրերն են կարող անոտացվել:
   • @Retention: Նշում է, թե որ փուլում է անոտացիան առկա (SOURCE, BINARY, RUNTIME):
   • @Repeatable: Позволяет применять аннотацию несколько раз к одному и тому же элементу.
   • @MustBeDocumented: Նշում է, որ անոտացիան պետք է լինի հանրային API-ի մաս, որը գեներացվում է փաստաթղթավորման գործիքով:

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

Անոտացիաները լայնորեն օգտագործվում են Կոտլինում JVM ֆրեյմվորկների (Spring, Android), սերիալիզացիայի (Kotlinx.serialization), թեստավորման (JUnit) և սեփական գրադարանների ստեղծման համար, որոնք հիմնված են մետա-տեղեկատվության վրա։