Kotlin annotations

Annotations in Kotlin allow us to attach metadata to our code. While annotations do not directly affect program execution, they provide supplementary information that can be used by compilers, development tools, and frameworks during code analysis, compilation, or runtime processing. In Kotlin, annotations can be applied to:

1. Classes and interfaces
2. Functions and constructors
3. Properties and parameters
4. Type parameters
5. Expressions and files

The parameters passed to an annotation must be compile-time constants. Kotlin supports the following types as annotation parameters:

1. Primitive types (Int, Long, etc.)
2. String
3. Enum constants
4. Class references (using ::class)
5. Other annotations
6. Arrays of the above types 

Applying Annotation

To apply an annotation, we prefix it with the @ symbol followed by the annotation name. For example, if we want to apply an annotation named Positive, we should write the following if we want to write annotation Pos

@Positive
val number: Int = 10

If the annotation requires arguments, we pass them inside parentheses.

@AllowedLanguage("Kotlin")
val language: String = "Kotlin"

If an annotation is used as a parameter inside another annotation, we omit the @ symbol.

@Deprecated("This function is deprecated", ReplaceWith("newFunction()"))
fun oldFunction() {}

When passing a class as a parameter, we use the ::class syntax:

@Throws(IOException::class)
fun readFile() {
    // ...
} 

Declaring Annotation

To declare an annotation, the class keyword is prefixed with the annotation keyword. By their nature, declarations of annotation cannot contain any code. While declaring our custom annotations, we should specify to which code elements they might apply and where they should be stored. 
The simplest annotation contains no parameters - 

annotation class MyClass

An annotation that requires parameter is much similar to a class with a primary constructor -  

annotation class Suffix(val s: String)

Annotate a constructor

We can also annotate the constructor of a class. It can be done by using the constructor keyword for constructor declaration and placing the annotation before it. 

class MyClass @Inject constructor(val dependency: Dependency) 

Annotate a property

We can annotate the properties of class by adding an annotation to the properties. In below example, we assume that an Lang instance is valid if the value of the name is either Kotlin or Java. 

class Language(
    @AllowedLanguages(["Kotlin", "Java"])
    val name: String
) 

Some in-built annotations

Kotlin also provides certain in-built annotations, that are used to provide more attributes to user-defined annotations. To be precise, these annotations are used to annotate annotations. 

1. @Target

This annotation specifies the places where the annotated annotation can be applied such as classes, functions, constructors, type parameters, etc. When an annotation is applied to the primary constructor for a class, the constructor keyword is specified before the constructor. 

Example: 

@Target(AnnotationTarget.CONSTRUCTOR, AnnotationTarget.LOCAL_VARIABLE)
annotation class AnnotationDemo2

class ABC @AnnotationDemo2 constructor(val count:Int){
    fun display(){
        println("Constructor annotated")
        println("Count is $count")
    }
}
fun main(){
    val obj =  ABC(5)
    obj.display()
    @AnnotationDemo2 val message: String
    message = "Hello"
    println("Local parameter annotated")
    println(message)
}

Output: 

Constructor annotated
Count is 5
Local parameter annotated
Hello

2. @Retention

Specifies how long the annotation is retained. It accepts a value from the AnnotationRetention enum:

• SOURCE – Discarded by the compiler
• BINARY – Present in the class file, but not available at runtime
• RUNTIME – Available during runtime via reflection

Example:

//Specifying an annotation with runtime policy 
@Retention(AnnotationRetention.RUNTIME)
annotation class AnnotationDemo3 

@AnnotationDemo3 fun main(){
    println("Main function annotated")
}

Output:  

Main function annotated

3. @Repeatable

Allows an annotation to be applied multiple times to the same element. This requires retention to be at least SOURCE. 

Example: 

@Repeatable
@Retention(AnnotationRetention.SOURCE)
annotation class AnnotationDemo4 (val value: Int)

@AnnotationDemo4(4)
@AnnotationDemo4(5)
fun main(){
    println("Repeatable Annotation applied on main")
}

Output: 

Repeatable Annotation applied on main