Annotations attach metadata and extra semantics to a declaration. That metadata can be available to source-processing tools, compiled class files, or run-time code, depending on the annotation’s configuration. In Kotlin, write an annotation before the declaration it marks: @MyAnnotation(params). This supports compiler, IDE, external-tool, and library-specific behavior without changing the declaration’s main code. section 12.1 section 12.0 section 12.3
Mark an API for replacement
Use @Deprecated to tell callers that an API should no longer be used and to offer a migration path. @Deprecated("Use removeAt(index) instead.", ReplaceWith("removeAt(index)")) fun remove(index: Int) { /* ... */ } A deprecation can be a WARNING, ERROR, or HIDDEN. IDE support can present the replacement and offer an automatic quick fix, making an API transition clearer for callers. section 12.1.1 section 12.1.1
Apply annotations deliberately when Kotlin declarations map to JVM elements:
- Annotate classes, functions, properties, and other supported declarations with @AnnotationName(...). Annotation arguments may be primitives, strings, enums, class references, annotations, or arrays of those values. section 12.1.1 section 12.3
- Use a use-site target when a property produces several Java-facing elements. For example, @get:JvmName("obtainCertificate") and @set:JvmName("putCertificate") rename the generated accessor methods for Java callers. section 12.1.2 section 12.1.2
- Suppress a narrowly scoped compiler warning with an annotation on a local declaration, such as @Suppress("UNCHECKED_CAST"). section 12.1.2
Define custom metadata with annotation class declarations. An annotation class has no body; its constructor parameters must be val properties. Kotlin treats use as a constructor call, so @JsonName("alias") can supply the first parameter positionally, while annotations declared in Java require named arguments except for value. A class reference argument uses ::class and can constrain acceptable implementation types with KClass. section 12.1.4 section 12.1.4 section 12.1.6
Customize JSON property handling
Annotations can alter serialization without hard-coding special cases into a data class. data class Person( @JsonName("alias") val firstName: String, @JsonExclude val age: Int? = null ) At run time, reflection can inspect property annotations. findAnnotation<JsonExclude>() filters properties from serialization; findAnnotation<JsonName>() supplies a JSON name when present and otherwise falls back to the property name. A @CustomSerializer(DateSerializer::class) annotation can select a serializer for an individual property. section 12.1.3 section 12.2.3 section 12.2.3
class CertificateManager {
@get:JvmName("obtainCertificate") #1
@set:JvmName("putCertificate") #2
var certificate: String = "-----BEGIN PRIVATE KEY-----"
}
Compare getter and setter use-site targets on one Kotlin property, then see the Java accessor names they produce. section 12.1.2
