From 4383335168338df9bbbe2a63cb213a68d0858104 Mon Sep 17 00:00:00 2001 From: Mikhael Bogdanov Date: Wed, 30 May 2018 15:04:54 +0200 Subject: [PATCH] Update @JvmDefault documentation --- .../stdlib/jvm/src/kotlin/jvm/JvmDefault.kt | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/libraries/stdlib/jvm/src/kotlin/jvm/JvmDefault.kt b/libraries/stdlib/jvm/src/kotlin/jvm/JvmDefault.kt index b7728dc73da..771859b2105 100644 --- a/libraries/stdlib/jvm/src/kotlin/jvm/JvmDefault.kt +++ b/libraries/stdlib/jvm/src/kotlin/jvm/JvmDefault.kt @@ -11,10 +11,21 @@ import kotlin.internal.RequireKotlinVersionKind /** * Specifies that a JVM default method should be generated for non-abstract Kotlin interface member. * - * This annotation requires explicit compilation flag to be enabled: `-Xenable-jvm-default`. - * Also this requires jvmTarget 1.8 or higher. - * Adding or removing this annotation to an interface member is a binary incompatible change. - * @JvmDefault methods are excluded from interface delegation. + * Usages of this annotation require an explicit compilation argument to be specified: + * either `-Xjvm-default=enable` or `-Xjvm-default=compatibility`. + * + * * with `-Xjvm-default=enable`, only default method in interface is generated for each @[JvmDefault] method. + * In this mode, annotating an existing method with @[JvmDefault] can break binary compatibility, because it will effectively + * remove the method from the `DefaultImpls` class. + * * with `-Xjvm-default=compatibility`, in addition to the default interface method, a compatibility accessor is generated + * in the `DefaultImpls` class, that calls the default interface method via a synthetic accessor. + * In this mode, annotating an existing method with @[JvmDefault] is binary compatible, but results in more methods in bytecode. + * + * Removing this annotation from an interface member is a binary incompatible change in both modes. + * + * Generation of default methods is only possible with JVM target bytecode version 1.8 (`-jvm-target 1.8`) or higher. + * + * @[JvmDefault] methods are excluded from interface delegation. */ @SinceKotlin("1.2") @RequireKotlin("1.2.40", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)