Annotations¶

Annotations play a crucial role in Kotlin, providing metadata and influencing code behavior. The Analysis API allows you to access and analyze annotations applied to both declarations and types.

KaAnnotated¶

KaAnnotated is an interface exposing a list of annotations. All types and almost all symbols implement it.

graph TD
  KaAnnotated
  KaAnnotated --> KaType
  KaAnnotated --> KaAnnotatedSymbol
  KaAnnotatedSymbol --> KaFileSymbol
  KaAnnotatedSymbol --> KaScriptSymbol
  KaAnnotatedSymbol --> KaDeclarationSymbol

The only property KaAnnotated declares is annotations of the KaAnnotationList type. KaAnnotationList itself is implements a List<KaAnnotation>, so you can directly iterate over annotations:

context(session: KaSession)
fun processAnnotations(symbol: KaDeclarationSymbol) {
    for (anno in symbol.annotations) {
        // Process the 'annotation'
    }
}

KaAnnotationList is not just a list. It can also efficiently check whether an annotation with some ClassId is there:

context(session: KaSession)
fun hasDeprecatedAnnotation(symbol: KaDeclarationSymbol) {
    val classId = ClassId.fromString("kotlin/Deprecated")
    return classId in symbol.annotations
}

You can also get a list of annotations with a specific ClassId. Kotlin allows repeatable annotations, so a list of them is returned:

context(session: KaSession)
fun findDeprecatedAnnotation(symbol: KaDeclarationSymbol): KaAnnotation? {
    val classId = ClassId.fromString("kotlin/Deprecated")
    return symbol.annotations[classId].firstOrNull()
}

Finally, KaAnnotationList exposes a collection of all annotation ClassIds:

context(session: KaSession)
fun collectAnnotations(types: List<KaType>): Set<ClassId> {
    return types.flatMapTo(HashSet()) { it.annotations.classIds }
}

Use-Site Targets¶

Annotations on declarations can have use-site targets, specifying where the annotation applies (e.g., property, field, or parameter). You can use the useSiteTarget property of KaAnnotation to access this information.