From 137e5d67d0abd66a6555664db8ce4718348415c7 Mon Sep 17 00:00:00 2001 From: Vsevolod Tolstopyatov Date: Thu, 22 Sep 2022 13:57:45 +0000 Subject: [PATCH] Scrupulously document OptIn-related annotations #KT-49425 Merge-request: KT-MR-7094 Merged-by: Vsevolod Tolstopyatov --- .../stdlib/src/kotlin/annotations/OptIn.kt | 125 +++++++++++++++--- 1 file changed, 108 insertions(+), 17 deletions(-) diff --git a/libraries/stdlib/src/kotlin/annotations/OptIn.kt b/libraries/stdlib/src/kotlin/annotations/OptIn.kt index 4fc9b18393e..3601e1c245a 100644 --- a/libraries/stdlib/src/kotlin/annotations/OptIn.kt +++ b/libraries/stdlib/src/kotlin/annotations/OptIn.kt @@ -1,5 +1,5 @@ /* - * Copyright 2010-2018 JetBrains s.r.o. and Kotlin Programming Language contributors. + * Copyright 2010-2022 JetBrains s.r.o. and Kotlin Programming Language contributors. * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file. */ @@ -7,16 +7,86 @@ package kotlin import kotlin.annotation.AnnotationRetention.* import kotlin.annotation.AnnotationTarget.* -import kotlin.internal.RequireKotlin -import kotlin.internal.RequireKotlinVersionKind import kotlin.reflect.KClass /** * Signals that the annotated annotation class is a marker of an API that requires an explicit opt-in. * - * Call sites of any declaration annotated with that marker should opt in to the API either by using [OptIn], + * Call sites of any declaration that is either annotated with such a marker or mentions in its signature any + * other declaration that requires opt-in should opt in to the API either by using [OptIn], * or by being annotated with that marker themselves, effectively causing further propagation of the opt-in requirement. * + * The intended uses of opt-in markers include, but are not limited to the following: + * - Experimental API for public preview that might change its semantics or affect binary compatibility. + * - Internal declarations that should not be used outside the declaring library, but are `public` for technical reasons. + * - Fragile or delicate API that needs a lot of expertise to use and thus require an explicit opt-in. + * + * ## Contagiousness + * + * When a declaration is marked with an opt-in requirement, it is considered to be contagious, meaning that all its uses + * or mentions in other declarations will require an explicit opt-in. + * A rule of thumb for propagating is the following: if the marked declaration ceases to exist, only + * the places with explicit opt-in (or the corresponding warning) will break. This rule does not imply transitivity, + * e.g. the propagation does not propagate opt-in through inlining, making it the responsibility `inline` function author + * to mark it properly. + * + * ### Type scopes + * + * A type is considered requiring opt-in if it is marked with an opt-in marker, or the outer declaration (class or interface) requires opt-in. + * Any use of any declaration that mentions such type in its signature will require an explicit opt-in, even if it is not used + * directly on the call site, and even if such declarations do not require opt-in directly. + * + * For example, consider the following declarations that are marked with non-propagating opt-in: + * ``` + * @UnstableApi + * class Unstable + * + * @OptIn(UnstableApi::class) + * fun foo(): Unstable = Unstable() + * + * @OptIn(UnstableApi::class) + * fun bar(arg: Unstable = Unstable()) {} + * + * @OptIn(UnstableApi::class) + * fun Unstable?.baz() {} + * ``` + * and their respective call sites: + * ``` + * fun outerFun() { + * val s = foo() + * bar() + * null.baz() + * } + * ``` + * Even though call sites do not mention `Unstable` type directly, the corresponding opt-in warning or error will be triggered + * in each call site due to propagation contagiousness. Note that the propagation is not transitive, i.e. calls to `outerFun` + * itself would not trigger any further opt-in requirements. + * + * ### Lexical scopes + * + * If a type requires an opt-in, such requirement is propagated to its lexical scope and all its nested declarations. + * For example, for the following scope: + * ``` + * @UnstableApi + * class Unstable { + * fun memberFun() = ... + * + * class NestedClass { + * fun nestedFun() = ... + * } + * } + * ``` + * + * Any use of `Unstable`, `NestedClass`, or their member functions will require an explicit opt-in. + * + * ### Overridden declarations + * + * Opt-in markers are also propagated through the inheritance and interface implementation. + * If the base declaration requires an opt-in, overriding it requires either an explicit opt-in or + * propagating the opt-in requirement. + * + * See also [Kotlin language documentation](https://kotlinlang.org/docs/opt-in-requirements.html) for more information. + * * @property message message to be reported on usages of API without an explicit opt-in, or empty string for the default message. * The default message is: "This declaration is experimental and its usage should be marked with 'Marker' * or '@OptIn(Marker::class)'", where `Marker` is the opt-in requirement marker. @@ -37,7 +107,7 @@ public annotation class RequiresOptIn( /** Specifies that a warning should be reported on incorrect usages of this API. */ WARNING, - /** Specifies that an error should be reported on incorrect usages of this API. */ + /** Specifies that a compilation error should be reported on incorrect usages of this API. */ ERROR, } } @@ -45,6 +115,15 @@ public annotation class RequiresOptIn( /** * Allows to use the API denoted by the given markers in the annotated file, declaration, or expression. * If a declaration is annotated with [OptIn], its usages are **not** required to opt in to that API. + * + * [markerClass] specifies marker annotations that require explicit opt-in. The marker annotation is + * not required to be itself marked with [RequiresOptIn] to enable gradual migration of API from requiring opt-in to the regular one, + * yet declaring such `OptIn` yields a compilation warning. + * + * See also [Kotlin language documentation](https://kotlinlang.org/docs/opt-in-requirements.html) for more information. + * + * @property markerClass specifies marker annotations that require explicit opt-in. + * @see RequiresOptIn for a detailed description of opt-in semantics and propagation rules. */ @Target( CLASS, PROPERTY, LOCAL_VARIABLE, VALUE_PARAMETER, CONSTRUCTOR, FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER, EXPRESSION, FILE, TYPEALIAS @@ -56,7 +135,11 @@ public annotation class OptIn( ) /** - * Opt-in marker annotation which allows to use [SubclassOptInRequired]. + * This annotation marks the experimental preview of the language feature [SubclassOptInRequired]. + * + * > Note that this API is in a preview state and has a chance of being changed in the future. + * Do not use it if you develop a library since your library can become source incompatible + * with the future versions of Kotlin. */ @Target(CLASS) @Retention(BINARY) @@ -64,21 +147,29 @@ public annotation class OptIn( public annotation class ExperimentalSubclassOptIn /** - * Forbids creation of subclasses/sub-interfaces from the annotated class/interface without explicit [OptIn]. + * Annotation that marks open for subclassing classes and interfaces, and makes implementation + * and extension of such declarations as requiring an explicit opt-in. * - * This annotation is devoted to specific case when we want subclassing to be experimental. - * In this case we annotated the base class or interface with [SubclassOptInRequired]. - * Without an explicit opt-in we have a compilation error/warning on the subclass/sub-interface after that. + * When applied, any attempt to subclass the target declaration will trigger an opt-in + * with the corresponding level and message. * - * There are three ways to negate this error/warning: - *
  1. Annotate subclass or interface with the marker annotation. In this case opt-in is propagated.
    2. - *
  2. Annotate subclass or interface with [OptIn]. In this case opt-in isn't propagated.
    3. - *
  3. Annotate subclass or interface with [SubclassOptInRequired]. In this case opt-in is propagated to subclasses/interfaces only.
    4. - *
+ * The intended uses of subclass opt-in markers include, but are not limited to the following API: + * - Stable to use, but unstable to implement due to its further evolution. + * - Stable to use, but closed for 3rd-part implementations due to internal or technical reasons. + * - Stable to use, but delicate or fragile to implement. + * - Stable to use, but with a contract that may be weakened in the future in a backwards-incompatible + * manner for external implementations. * - * Note that [SubclassOptInRequired] does not negate an opt-in usage error itself. + * Contrary to regular [RequiresOptIn], there are three ways to opt-in into the subclassing requirement: + * - Annotate declaration with the marker annotation, making it propagating. + * - Annotate declaration with [OptIn] in order to opt in into the provided guarantees in a non-propagating manner. + * - Annotate declaration with [SubclassOptInRequired] with the same marker class, making it further propagating only for subclassing. * - * @property markerClass an opt-in marker to be required + * Uses of this annotation are limited to open and abstract classes, and non-`fun` interfaces. + * Any other uses allowed by `CLASS` annotation target yield a compilation error. + * + * @property markerClass specifies marker annotation that require explicit opt-in. + * @see RequiresOptIn for a detailed description of opt-in semantics and propagation rules. */ @Target(CLASS) @Retention(BINARY)