Improve documentation of experimental annotations

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
+ * Signals that the annotated annotation class is a marker of an experimental API.
- * considered an experimental declaration and its call sites should accept the experimental aspect of it either by using [UseExperimental],
+ *
+ * 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`.

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 <T> sequence(@BuilderInference block: suspend SequenceScope<T>.() -> Unit): Sequence<T>
+ * ```
+ * 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)

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)

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.
+ * This marker distinguishes the experimental contract declaration API and is used to opt-in for that feature
- * Any declaration annotated with that marker must be used with the [UseExperimental] annotation
+ * when declaring contracts of user functions.
- * or the compiler argument `-Xuse-experimental=kotlin.contracts.ExperimentalContracts`.
+ *
+ * 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")

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)

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
+ * Usages of such API will be reported as warnings unless an explicit opt-in with
- * or the `-Xuse-experimental=kotlin.ExperimentalUnsignedTypes` compiler option is done.
+ * 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)