azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Scrupulously document OptIn-related annotations

Browse Source 
#KT-49425

Merge-request: KT-MR-7094
Merged-by: Vsevolod Tolstopyatov <qwwdfsad@gmail.com>
This commit is contained in:
Vsevolod Tolstopyatov
2022-09-22 13:57:45 +00:00
committed by Space
parent 39a44d4ccb
commit 137e5d67d0
1 changed files with 108 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/src/kotlin/annotations/OptIn.kt
+108 -17
View File
@@ -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:
* <ol><li>Annotate subclass or interface with the marker annotation. In this case opt-in is propagated.</li>
* <li>Annotate subclass or interface with [OptIn]. In this case opt-in isn't propagated.</li>
* <li>Annotate subclass or interface with [SubclassOptInRequired]. In this case opt-in is propagated to subclasses/interfaces only.</li>
* </ol>
* 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)