From 980feffffaaf95f0f0be3172c9730c92efb1129f Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Wed, 6 Sep 2017 19:52:51 +0300 Subject: [PATCH] Improve @PublishedApi annotation docs #KT-19881 --- core/builtins/src/kotlin/Annotations.kt | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/core/builtins/src/kotlin/Annotations.kt b/core/builtins/src/kotlin/Annotations.kt index 6e09a034b7d..def1fb8455a 100644 --- a/core/builtins/src/kotlin/Annotations.kt +++ b/core/builtins/src/kotlin/Annotations.kt @@ -130,7 +130,15 @@ public annotation class DslMarker /** - * Specifies that this part of internal API is effectively public exposed by using in public inline function + * When applied to a class or a member with internal visibility allows to use it from public inline functions and + * makes it effectively public. + * + * Public inline functions cannot use non-public API, since if they are inlined, those non-public API references + * would violate access restrictions at a call site (http://kotlinlang.org/docs/reference/inline-functions.html#public-inline-restrictions). + * + * To overcome this restriction an `internal` declaration can be annotated with the `@PublishedApi` annotation: + * - this allows to call that declaration from public inline functions; + * - the declaration becomes effectively public, and this should be considered with respect to binary compatibility maintaining. */ @Target(AnnotationTarget.CLASS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY) @Retention(AnnotationRetention.BINARY)