diff --git a/libraries/stdlib/src/kotlin/annotations/Experimental.kt b/libraries/stdlib/src/kotlin/annotations/Experimental.kt index 679a33f28c0..02f584af870 100644 --- a/libraries/stdlib/src/kotlin/annotations/Experimental.kt +++ b/libraries/stdlib/src/kotlin/annotations/Experimental.kt @@ -13,8 +13,10 @@ import kotlin.internal.RequireKotlinVersionKind import kotlin.reflect.KClass /** - * Signals that the annotated annotation class is a marker of an experimental API. Any declaration annotated with that marker is thus - * considered an experimental declaration and its call sites should accept the experimental aspect of it either by using [UseExperimental], + * Signals that the annotated annotation class is a marker of an experimental API. + * + * Any declaration annotated with that marker is considered an experimental declaration + * and its call sites should accept the experimental aspect of it either by using [UseExperimental], * or by being annotated with that marker themselves, effectively causing further propagation of that experimental aspect. * * This class is experimental itself and can only be used with the compiler argument `-Xuse-experimental=kotlin.Experimental`. diff --git a/libraries/stdlib/src/kotlin/annotations/Inference.kt b/libraries/stdlib/src/kotlin/annotations/Inference.kt index 6fc4db97325..3ac06e83f6c 100644 --- a/libraries/stdlib/src/kotlin/annotations/Inference.kt +++ b/libraries/stdlib/src/kotlin/annotations/Inference.kt @@ -9,7 +9,26 @@ import kotlin.annotation.AnnotationTarget.* import kotlin.experimental.ExperimentalTypeInference /** - * Marks the API which usages is dependent on the experimental builder inference. + * Allows to infer generic type arguments of a function from the calls in the annotated function parameter of that function. + * + * When this annotation is placed on a generic function parameter of a function, + * it enables to infer the type arguments of that generic function from the lambda body passed to that parameter. + * + * The calls that affect inference are either members of the receiver type of an annotated function parameter or + * extensions for that type. The extensions must be themselves annotated with `@BuilderInference`. + * + * Example: we declare + * ``` + * fun sequence(@BuilderInference block: suspend SequenceScope.() -> Unit): Sequence + * ``` + * and use it like + * ``` + * val result = sequence { yield("result") } + * ``` + * Here the type argument of the resulting sequence is inferred to `String` from + * the argument of the [SequenceScope.yield] function, that is called inside the lambda passed to [sequence]. + * + * Note: this annotation is experimental, see [ExperimentalTypeInference] on how to opt-in for it. */ @Target(VALUE_PARAMETER, FUNCTION, PROPERTY) @Retention(AnnotationRetention.BINARY) diff --git a/libraries/stdlib/src/kotlin/annotations/Multiplatform.kt b/libraries/stdlib/src/kotlin/annotations/Multiplatform.kt index db4bc314c78..2783ffc777f 100644 --- a/libraries/stdlib/src/kotlin/annotations/Multiplatform.kt +++ b/libraries/stdlib/src/kotlin/annotations/Multiplatform.kt @@ -9,6 +9,13 @@ import kotlin.annotation.AnnotationTarget.* import kotlin.internal.RequireKotlin import kotlin.internal.RequireKotlinVersionKind +/** + * The experimental multiplatform support API marker. + * + * Any usage of a declaration annotated with `@ExperimentalMultiplatform` must be accepted either by + * annotating that usage with the [UseExperimental] annotation, e.g. `@UseExperimental(ExperimentalMultiplatform::class)`, + * or by using the compiler argument `-Xuse-experimental=kotlin.ExperimentalMultiplatform`. + */ @Experimental @Target( CLASS, @@ -28,10 +35,14 @@ import kotlin.internal.RequireKotlinVersionKind public annotation class ExperimentalMultiplatform /** + * Marks an expected annotation class that it isn't required to have actual counterparts in all platforms. + * * This annotation is only applicable to `expect` annotation classes in multi-platform projects and marks that class as "optional". * Optional expected class is allowed to have no corresponding actual class on the platform. Optional annotations can only be used * to annotate something, not as types in signatures. If an optional annotation has no corresponding actual class on a platform, * the annotation entries where it's used are simply erased when compiling code on that platform. + * + * Note: this annotation is experimental, see [ExperimentalMultiplatform] on how to opt-in for it. */ @Target(ANNOTATION_CLASS) @Retention(AnnotationRetention.BINARY) diff --git a/libraries/stdlib/src/kotlin/contracts/ContractBuilder.kt b/libraries/stdlib/src/kotlin/contracts/ContractBuilder.kt index 42200dc3e41..d5a30fd3f56 100644 --- a/libraries/stdlib/src/kotlin/contracts/ContractBuilder.kt +++ b/libraries/stdlib/src/kotlin/contracts/ContractBuilder.kt @@ -9,9 +9,12 @@ import kotlin.internal.ContractsDsl import kotlin.internal.InlineOnly /** - * Marker of the use experimental contracts API. - * Any declaration annotated with that marker must be used with the [UseExperimental] annotation - * or the compiler argument `-Xuse-experimental=kotlin.contracts.ExperimentalContracts`. + * This marker distinguishes the experimental contract declaration API and is used to opt-in for that feature + * when declaring contracts of user functions. + * + * Any usage of a declaration annotated with `@ExperimentalContracts` must be accepted either by + * annotating that usage with the [UseExperimental] annotation, e.g. `@UseExperimental(ExperimentalContracts::class)`, + * or by using the compiler argument `-Xuse-experimental=kotlin.contracts.ExperimentalContracts`. */ @Retention(AnnotationRetention.BINARY) @SinceKotlin("1.3") diff --git a/libraries/stdlib/src/kotlin/experimental/inferenceMarker.kt b/libraries/stdlib/src/kotlin/experimental/inferenceMarker.kt index 6c8dc9db493..0a8a1a7a74a 100644 --- a/libraries/stdlib/src/kotlin/experimental/inferenceMarker.kt +++ b/libraries/stdlib/src/kotlin/experimental/inferenceMarker.kt @@ -6,7 +6,11 @@ package kotlin.experimental /** - * Marker of the use experimental type inference features + * The experimental type inference augmenting annotations marker. + * + * Any usage of a declaration annotated with `@ExperimentalTypeInference` must be accepted either by + * annotating that usage with the [UseExperimental] annotation, e.g. `@UseExperimental(ExperimentalTypeInference::class)`, + * or by using the compiler argument `-Xuse-experimental=kotlin.experimental.ExperimentalTypeInference`. */ @Experimental(level = Experimental.Level.ERROR) @Retention(AnnotationRetention.BINARY) diff --git a/libraries/stdlib/unsigned/src/kotlin/annotations/Unsigned.kt b/libraries/stdlib/unsigned/src/kotlin/annotations/Unsigned.kt index 268d23d4432..11136f6003a 100644 --- a/libraries/stdlib/unsigned/src/kotlin/annotations/Unsigned.kt +++ b/libraries/stdlib/unsigned/src/kotlin/annotations/Unsigned.kt @@ -13,8 +13,11 @@ import kotlin.internal.RequireKotlinVersionKind /** * Marks the API that is dependent on the experimental unsigned types, including those types themselves. * - * Usages of such API will be reported as warnings unless an explicit opt-in with the [UseExperimental] annotation - * or the `-Xuse-experimental=kotlin.ExperimentalUnsignedTypes` compiler option is done. + * Usages of such API will be reported as warnings unless an explicit opt-in with + * the [UseExperimental] annotation, e.g. `@UseExperimental(ExperimentalUnsignedTypes::class)`, + * or with the `-Xuse-experimental=kotlin.ExperimentalUnsignedTypes` compiler option is given. + * + * It's recommended to propagate the experimental status to the API that depends on unsigned types by annotating it with this annotation. */ @Experimental(level = Experimental.Level.WARNING) @Target(CLASS, ANNOTATION_CLASS, PROPERTY, FIELD, LOCAL_VARIABLE, VALUE_PARAMETER, CONSTRUCTOR, FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER, TYPEALIAS)