IntroducedAt

Instructs the Kotlin compiler to generate overloads by specifying the versions in which optional parameters were introduced, after the initial publication of the library. Generated overloads are hidden and aimed to maintain binary compatibility, they let users of your library upgrade to the newer version without having to recompile their code.

Value parameters with the same version are assumed to have been introduced at the same time. For example, given the signature,

fun example(a: A, @IntroducedAt("1.1") b: B = defaultB, @IntroducedAt("1.1") c: C = defaultC, @IntroducedAt("1.4") d: D = defaultD)

the compiler generates overloads corresponding to the following,

fun example(a: A) // hidden, initial version
fun example(a: A, @IntroducedAt("1.1") b: B = defaultB, @IntroducedAt("1.1") c: C = defaultC) // hidden, version 1.1

// non-hidden overload, version 1.4
fun example(a: A, @IntroducedAt("1.1") b: B = defaultB, @IntroducedAt("1.1") c: C = defaultC, @IntroducedAt("1.4") d: D = defaultD)

Note that once a user of the library compiles against the new version, the most recent overload (the one with all the optional parameters) is chosen for code generation. That means that from that point on the older version of the library may no longer be used as a dependency.

Restrictions on IntroducedAt

The version string must follow the Apache Maven version format. Versions in a signature must appear in ascending order.

• Parameters without this annotation are assumed to correspond to the "initial version".

• If the last parameter has a function type, this rule may be disregarded. This makes it possible to introduce optional parameters before the trailing lambda position.

It is not allowed to use this annotation on extension receivers or context parameters, only in value parameters.

Value parameters marked with the annotation must have a default value. Default values for optional arguments may not depend on values from a newer version.

It is not allowed to use this annotation on non-final methods, including abstract methods and interfaces. These restrictions are similar to those of kotlin.jvm.JvmName.

It is not allowed to use this annotation in combination with kotlin.jvm.JvmOverloads.

If a data class constructor has parameters annotated with the annotation, the compiler also generates the corresponding overloads of its copy method in addition to the constructor overloads.

For more information you can check the full design (KEEP) document.