Kotlin language specification

Annotations are a form of syntactically-defined metadata which may be associated with different entities in a Kotlin program. Annotations are specified in the source code of the program and may be accessed on a particular platform using platform-specific mechanisms both by the compiler (and source-processing tools) and at runtime (using reflection facilities). Values of annotation types can also be created directly, but are usually operated on using platform-specific facilities.

An annotation value is a value of a special annotation type. An annotation type is a special kind of class type which is allowed to include read-only properties of the following types:

Annotation classes are not allowed to have any member functions, constructors or mutable properties. They are also not allowed to have declared supertypes and are considered to be implicitly derived from kotlin.Annotation.

The retention level of an annotation declares which compilation artifacts (for a particular compiler on a particular platform) retain this kind of annotation. There are the following types of retention available:

For availability and particular ways of accessing the metadata specified by these annotations please refer to the corresponding platform-specific documentation.

The target of a particular type of annotations is the kind of program entity which this annotations may be placed on. There are the following targets available:

Annotations are declared using annotation class declarations. See the corresponding section for details.

Annotations may be declared repeatable (meaning that the same annotation may be applied to the same entity more than once) or non-repeatable (meaning that only one annotation of a particular type may be applied to the same entity).

kotlin.annotation.Retention is an annotation which is only used on annotation classes to specify their annotation retention level. It has the following single field:

kotlin.annotation.AnnotationRetention is an enum class with the following values (see Annotation retention section for details):

kotlin.annotation.Target is an annotation which is only used on annotation classes to specify targets those annotations are valid for. It has the following single field:

kotlin.annotation.AnnotationTarget is an enum class with the following values (see Annotation targets section for details):

kotlin.annotation.Repeatable is an annotation which is only used on annotation classes to specify whether this particular annotation is repeatable. Annotations are non-repeatable by default.

kotlin.RequiresOptIn is an annotation class with two fields:

This annotation is used to introduce implementation-defined experimental language or standard library features.

kotlin.OptIn is an annotation class with a single field:

This annotation is used to explicitly mark declarations which use experimental features marked by kotlin.RequiresOptIn.

It is implementation-defined how this annotation is processed.

kotlin.Deprecated is an annotation class with the following fields:

kotlin.ReplaceWith is itself an annotation class containing the information on how to perform the replacement in case it is provided. It has the following fields:

kotlin.Deprecated is a built-in annotation supporting the deprecation cycle for declarations: marking some declarations as outdated, soon to be replaced with other declarations, or not recommended for use. It is implementation-defined how this annotation is processed, with the following recommendations:

kotlin.Suppress is an annotation class with the following single field:

kotlin.Suppress is used to optionally mark any piece of code as suppressing some language feature, such as a compiler warning, an IDE mechanism or a language feature. The names of features which one can suppress with this annotation are implementation-defined, as is the processing of this annotation itself.

kotlin.SinceKotlin is an annotation class with the following single field:

kotlin.SinceKotlin is used to mark a declaration which is only available since a particular version of the language. These mostly refer to standard library declarations. It is implementation-defined how this annotation is processed.

kotlin.UnsafeVariance is an annotation class with no fields which is only applicable to types. Any type instance marked by this annotation explicitly states that the variance errors arising for this particular type instance are to be ignored by the compiler.

kotlin.DslMarker is an annotation class with no fields which is applicable only to other annotation classes. An annotation class annotated with kotlin.DslMarker is marked as a marker of a specific DSL (domain-specific language). Any type annotated with such a marker is said to belong to that specific DSL. This affects overload resolution in the following way: no two implicit receivers with types belonging to the same DSL are available in the same scope. See Overload resolution section for details.

kotlin.PublishedApi is an annotation class with no fields which is applicable to any declaration. It may be applied to any declaration with internal visibility to make it available to public inline declarations. See Declaration visibility section for details.

Marks the annotated function of function argument as eligible for builder-style type inference. See corresponding section for details.

In some cases we may want to limit which suspending functions can be called in another suspending function with an extension receiver of a specific type; i.e., if we want to provide a coroutine-enabled DSL, but disallow the use of arbitrary suspending functions. To do so, the type T of that extension receiver needs to be annotated with kotlin.RestrictSuspension, which enables the following limitations.

This annotation is used to allow using lambda return type to refine function applicability during overload resolution. Further details are available in the corresponding section.