diff options
Diffstat (limited to 'kotlinx-coroutines-core/common/src/Annotations.kt')
| -rw-r--r-- | kotlinx-coroutines-core/common/src/Annotations.kt | 18 |
1 files changed, 17 insertions, 1 deletions
diff --git a/kotlinx-coroutines-core/common/src/Annotations.kt b/kotlinx-coroutines-core/common/src/Annotations.kt index 70adad9b..724cc8cb 100644 --- a/kotlinx-coroutines-core/common/src/Annotations.kt +++ b/kotlinx-coroutines-core/common/src/Annotations.kt @@ -7,6 +7,22 @@ package kotlinx.coroutines import kotlinx.coroutines.flow.* /** + * Marks declarations in the coroutines that are **delicate** — + * they have limited use-case and shall be used with care in general code. + * Any use of a delicate declaration has to be carefully reviewed to make sure it is + * properly used and does not create problems like memory and resource leaks. + * Carefully read documentation of any declaration marked as `DelicateCoroutinesApi`. + */ +@MustBeDocumented +@Retention(value = AnnotationRetention.BINARY) +@RequiresOptIn( + level = RequiresOptIn.Level.WARNING, + message = "This is a delicate API and its use requires care." + + " Make sure you fully read and understand documentation of the declaration that is marked as a delicate API." +) +public annotation class DelicateCoroutinesApi + +/** * Marks declarations that are still **experimental** in coroutines API, which means that the design of the * corresponding declarations has open issues which may (or may not) lead to their changes in the future. * Roughly speaking, there is a chance that those declarations will be deprecated in the near future or @@ -59,7 +75,7 @@ public annotation class ObsoleteCoroutinesApi @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.TYPEALIAS, AnnotationTarget.PROPERTY) @RequiresOptIn( level = RequiresOptIn.Level.ERROR, message = "This is an internal kotlinx.coroutines API that " + - "should not be used from outside of kotlinx.coroutines. No compatibility guarantees are provided." + + "should not be used from outside of kotlinx.coroutines. No compatibility guarantees are provided. " + "It is recommended to report your use-case of internal API to kotlinx.coroutines issue tracker, " + "so stable API could be provided instead" ) |