From 0c89996e34700c2e7237a0a96417661dc0389f92 Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Thu, 24 May 2018 20:18:52 +0300 Subject: [PATCH] Introduce platform specific annotations as optional in common stdlib #KT-24478 --- libraries/stdlib/common/build.gradle | 1 + .../common/src/kotlin/JsAnnotationsH.kt | 15 +++ .../common/src/kotlin/JvmAnnotationsH.kt | 122 +++++++++++++++++- libraries/stdlib/js/build.gradle | 1 + libraries/stdlib/js/src/kotlin/annotations.kt | 12 +- .../stdlib/js/src/kotlin/annotationsJVM.kt | 25 +--- libraries/stdlib/jvm/build.gradle | 1 + .../jvm/annotations/JvmFlagAnnotations.kt | 8 +- .../jvm/annotations/JvmPlatformAnnotations.kt | 8 +- 9 files changed, 148 insertions(+), 45 deletions(-) create mode 100644 libraries/stdlib/common/src/kotlin/JsAnnotationsH.kt diff --git a/libraries/stdlib/common/build.gradle b/libraries/stdlib/common/build.gradle index 0453464a156..14c362c5c67 100644 --- a/libraries/stdlib/common/build.gradle +++ b/libraries/stdlib/common/build.gradle @@ -53,6 +53,7 @@ compileKotlinCommon { freeCompilerArgs = [ "-module-name", project.name, "-Xuse-experimental=kotlin.Experimental", + "-Xuse-experimental=kotlin.ExperimentalMultiplatform", "-Xuse-experimental=kotlin.ExperimentalUnsignedTypes", "-Xuse-experimental=kotlin.contracts.ExperimentalContracts", "-XXLanguage:+InlineClasses", diff --git a/libraries/stdlib/common/src/kotlin/JsAnnotationsH.kt b/libraries/stdlib/common/src/kotlin/JsAnnotationsH.kt new file mode 100644 index 00000000000..cc57e95e641 --- /dev/null +++ b/libraries/stdlib/common/src/kotlin/JsAnnotationsH.kt @@ -0,0 +1,15 @@ +/* + * Copyright 2010-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license + * that can be found in the license/LICENSE.txt file. + */ + +package kotlin.js + +import kotlin.annotation.AnnotationTarget.* + +/** + * Gives a declaration (a function, a property or a class) specific name in JavaScript. + */ +@Target(CLASS, FUNCTION, PROPERTY, CONSTRUCTOR, PROPERTY_GETTER, PROPERTY_SETTER) +@OptionalExpectation +public expect annotation class JsName(val name: String) \ No newline at end of file diff --git a/libraries/stdlib/common/src/kotlin/JvmAnnotationsH.kt b/libraries/stdlib/common/src/kotlin/JvmAnnotationsH.kt index 783c39a3cf7..78a80d4779c 100644 --- a/libraries/stdlib/common/src/kotlin/JvmAnnotationsH.kt +++ b/libraries/stdlib/common/src/kotlin/JvmAnnotationsH.kt @@ -7,13 +7,123 @@ package kotlin.jvm import kotlin.annotation.AnnotationTarget.* -@Target(FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER, FILE) -expect annotation class JvmName(val name: String) +/** + * Instructs the Kotlin compiler to generate overloads for this function that substitute default parameter values. + * + * If a method has N parameters and M of which have default values, M overloads are generated: the first one + * takes N-1 parameters (all but the last one that takes a default value), the second takes N-2 parameters, and so on. + */ +@Target(AnnotationTarget.FUNCTION, AnnotationTarget.CONSTRUCTOR) +@MustBeDocumented +@OptionalExpectation +public expect annotation class JvmOverloads() -@Target(FILE) -expect annotation class JvmMultifileClass() +/** + * Specifies that an additional static method needs to be generated from this element if it's a function. + * If this element is a property, additional static getter/setter methods should be generated. + * + * See the [Kotlin language documentation](https://kotlinlang.org/docs/reference/java-to-kotlin-interop.html#static-methods) + * for more information. + */ +@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER) +@MustBeDocumented +@OptionalExpectation +public expect annotation class JvmStatic() -expect annotation class JvmField() +/** + * Specifies the name for the Java class or method which is generated from this element. + * + * See the [Kotlin language documentation](https://kotlinlang.org/docs/reference/java-to-kotlin-interop.html#handling-signature-clashes-with-jvmname) + * for more information. + * @property name the name of the element. + */ +@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.FILE) +@MustBeDocumented +@OptionalExpectation +public expect annotation class JvmName(val name: String) +/** + * Instructs the Kotlin compiler to generate a multifile class with top-level functions and properties declared in this file as one of its parts. + * Name of the corresponding multifile class is provided by the [JvmName] annotation. + */ +@Target(AnnotationTarget.FILE) +@MustBeDocumented +@OptionalExpectation +public expect annotation class JvmMultifileClass() + + + +/** + * Instructs the Kotlin compiler not to generate getters/setters for this property and expose it as a field. + * + * See the [Kotlin language documentation](https://kotlinlang.org/docs/reference/java-to-kotlin-interop.html#instance-fields) + * for more information. + */ +@Target(AnnotationTarget.FIELD) +@MustBeDocumented +@OptionalExpectation +public expect annotation class JvmField() + +/** + * Instructs compiler to generate or omit wildcards for type arguments corresponding to parameters with + * declaration-site variance, for example such as `Collection` has. + * + * If the innermost applied `@JvmSuppressWildcards` has `suppress=true`, the type is generated without wildcards. + * If the innermost applied `@JvmSuppressWildcards` has `suppress=false`, the type is generated with wildcards. + * + * It may be helpful only if declaration seems to be inconvenient to use from Java. + */ +@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.TYPE) +@MustBeDocumented +@OptionalExpectation +public expect annotation class JvmSuppressWildcards(val suppress: Boolean = true) + +/** + * Instructs compiler to generate wildcard for annotated type arguments corresponding to parameters with declaration-site variance. + * + * It may be helpful only if declaration seems to be inconvenient to use from Java without wildcard. + */ +@Target(AnnotationTarget.TYPE) +@MustBeDocumented +@OptionalExpectation +public expect annotation class JvmWildcard() + + + +/** + * Marks the JVM backing field of the annotated property as `volatile`, meaning that writes to this field + * are immediately made visible to other threads. + */ @Target(FIELD) -expect annotation class Volatile() \ No newline at end of file +@MustBeDocumented +@OptionalExpectation +public expect annotation class Volatile() + +/** + * Marks the JVM backing field of the annotated property as `transient`, meaning that it is not + * part of the default serialized form of the object. + */ +@Target(FIELD) +@MustBeDocumented +@OptionalExpectation +public expect annotation class Transient() + +/** + * Marks the JVM method generated from the annotated function as `strictfp`, meaning that the precision + * of floating point operations performed inside the method needs to be restricted in order to + * achieve better portability. + */ +@Target(FUNCTION, CONSTRUCTOR, PROPERTY_GETTER, PROPERTY_SETTER, CLASS) +@MustBeDocumented +@OptionalExpectation +public expect annotation class Strictfp() + +/** + * Marks the JVM method generated from the annotated function as `synchronized`, meaning that the method + * will be protected from concurrent execution by multiple threads by the monitor of the instance (or, + * for static methods, the class) on which the method is defined. + */ +@Target(FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER) +@MustBeDocumented +@OptionalExpectation +public expect annotation class Synchronized() \ No newline at end of file diff --git a/libraries/stdlib/js/build.gradle b/libraries/stdlib/js/build.gradle index 9e17e9f8c4e..0f248a6f8b7 100644 --- a/libraries/stdlib/js/build.gradle +++ b/libraries/stdlib/js/build.gradle @@ -149,6 +149,7 @@ compileKotlin2Js { freeCompilerArgs += [ "-source-map-base-dirs", [builtinsSrcDir, jsSrcDir, commonSrcDir, commonSrcDir2].collect { file(it).absoluteFile }.join(File.pathSeparator), "-Xuse-experimental=kotlin.Experimental", + "-Xuse-experimental=kotlin.ExperimentalMultiplatform", "-Xuse-experimental=kotlin.contracts.ExperimentalContracts", "-XXLanguage:+InlineClasses", "-XXLanguage:-ReleaseCoroutines" diff --git a/libraries/stdlib/js/src/kotlin/annotations.kt b/libraries/stdlib/js/src/kotlin/annotations.kt index 31cfd54384f..9838991877f 100644 --- a/libraries/stdlib/js/src/kotlin/annotations.kt +++ b/libraries/stdlib/js/src/kotlin/annotations.kt @@ -60,11 +60,10 @@ internal annotation class marker * @property name the name which compiler uses both for declaration itself and for all references to the declaration. * It's required to denote a valid JavaScript identifier. * - * @since 1.1 */ @Retention(AnnotationRetention.BINARY) @Target(CLASS, FUNCTION, PROPERTY, CONSTRUCTOR, PROPERTY_GETTER, PROPERTY_SETTER) -annotation class JsName(val name: String) +public actual annotation class JsName(actual val name: String) /** * Denotes an `external` declaration that must be imported from native JavaScript library. @@ -93,11 +92,10 @@ annotation class JsName(val name: String) * It is not interpreted by the Kotlin compiler, it's passed as is directly to the target module system. * * @see JsNonModule - * @since 1.1 */ @Retention(AnnotationRetention.BINARY) @Target(CLASS, PROPERTY, FUNCTION, FILE) -annotation class JsModule(val import: String) +public annotation class JsModule(val import: String) /** * Denotes an `external` declaration that can be used without module system. @@ -125,11 +123,10 @@ annotation class JsModule(val import: String) * ``` * * @see JsModule - * @since 1.1 */ @Retention(AnnotationRetention.BINARY) @Target(CLASS, PROPERTY, FUNCTION, FILE) -annotation class JsNonModule +public annotation class JsNonModule /** * Adds prefix to `external` declarations in a source file. @@ -159,8 +156,7 @@ annotation class JsNonModule * Examples of valid qualifiers are: `foo`, `bar.Baz`, `_.$0.f`. * * @see JsModule - * @since 1.1 */ @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.FILE) -annotation class JsQualifier(val value: String) \ No newline at end of file +public annotation class JsQualifier(val value: String) \ No newline at end of file diff --git a/libraries/stdlib/js/src/kotlin/annotationsJVM.kt b/libraries/stdlib/js/src/kotlin/annotationsJVM.kt index 3ee6b321fb5..4a22f3a617e 100644 --- a/libraries/stdlib/js/src/kotlin/annotationsJVM.kt +++ b/libraries/stdlib/js/src/kotlin/annotationsJVM.kt @@ -7,28 +7,7 @@ package kotlin.jvm // these are used in common generated code in stdlib -@Target(AnnotationTarget.FUNCTION, AnnotationTarget.CONSTRUCTOR) -@Retention(AnnotationRetention.SOURCE) -internal annotation class JvmOverloads - -@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.FILE) -@Retention(AnnotationRetention.SOURCE) -@MustBeDocumented -@Suppress("ACTUAL_WITHOUT_EXPECT") // TODO: KT-19507 -internal actual annotation class JvmName(public actual val name: String) - -@Target(AnnotationTarget.FILE) -@Retention(AnnotationRetention.SOURCE) -@MustBeDocumented -@Suppress("ACTUAL_WITHOUT_EXPECT") // TODO: KT-19507 -internal actual annotation class JvmMultifileClass - -@Target(AnnotationTarget.FIELD) -@Retention(AnnotationRetention.SOURCE) -@MustBeDocumented -@Suppress("ACTUAL_WITHOUT_EXPECT") // TODO: KT-19507 -internal actual annotation class JvmField - +// TODO: find how to deprecate these ones @Target(AnnotationTarget.FIELD) @Retention(AnnotationRetention.SOURCE) @@ -36,4 +15,4 @@ public actual annotation class Volatile @Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER) @Retention(AnnotationRetention.SOURCE) -public annotation class Synchronized +public actual annotation class Synchronized diff --git a/libraries/stdlib/jvm/build.gradle b/libraries/stdlib/jvm/build.gradle index f9b6056fe00..32cf8a04b58 100644 --- a/libraries/stdlib/jvm/build.gradle +++ b/libraries/stdlib/jvm/build.gradle @@ -181,6 +181,7 @@ compileKotlin { "-Xnormalize-constructor-calls=enable", "-module-name", "kotlin-stdlib", "-Xuse-experimental=kotlin.Experimental", + "-Xuse-experimental=kotlin.ExperimentalMultiplatform", "-Xuse-experimental=kotlin.contracts.ExperimentalContracts", "-XXLanguage:-ReleaseCoroutines", "-XXLanguage:+InlineClasses" diff --git a/libraries/stdlib/jvm/runtime/kotlin/jvm/annotations/JvmFlagAnnotations.kt b/libraries/stdlib/jvm/runtime/kotlin/jvm/annotations/JvmFlagAnnotations.kt index 80f953bbd38..f02c3ef3367 100644 --- a/libraries/stdlib/jvm/runtime/kotlin/jvm/annotations/JvmFlagAnnotations.kt +++ b/libraries/stdlib/jvm/runtime/kotlin/jvm/annotations/JvmFlagAnnotations.kt @@ -3,6 +3,7 @@ * that can be found in the license/LICENSE.txt file. */ +@file:Suppress("ACTUAL_WITHOUT_EXPECT") // for building kotlin-runtime package kotlin.jvm import kotlin.annotation.AnnotationTarget.* @@ -11,7 +12,6 @@ import kotlin.annotation.AnnotationTarget.* * Marks the JVM backing field of the annotated property as `volatile`, meaning that writes to this field * are immediately made visible to other threads. */ -@Suppress("ACTUAL_WITHOUT_EXPECT") // for building kotlin-runtime @Target(FIELD) @Retention(AnnotationRetention.SOURCE) @MustBeDocumented @@ -24,7 +24,7 @@ public actual annotation class Volatile @Target(FIELD) @Retention(AnnotationRetention.SOURCE) @MustBeDocumented -public annotation class Transient +public actual annotation class Transient /** * Marks the JVM method generated from the annotated function as `strictfp`, meaning that the precision @@ -34,7 +34,7 @@ public annotation class Transient @Target(FUNCTION, CONSTRUCTOR, PROPERTY_GETTER, PROPERTY_SETTER, CLASS) @Retention(AnnotationRetention.SOURCE) @MustBeDocumented -public annotation class Strictfp +public actual annotation class Strictfp /** * Marks the JVM method generated from the annotated function as `synchronized`, meaning that the method @@ -44,4 +44,4 @@ public annotation class Strictfp @Target(FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER) @Retention(AnnotationRetention.SOURCE) @MustBeDocumented -public annotation class Synchronized \ No newline at end of file +public actual annotation class Synchronized \ No newline at end of file diff --git a/libraries/stdlib/jvm/runtime/kotlin/jvm/annotations/JvmPlatformAnnotations.kt b/libraries/stdlib/jvm/runtime/kotlin/jvm/annotations/JvmPlatformAnnotations.kt index 58b304a8054..4f6560fa8fb 100644 --- a/libraries/stdlib/jvm/runtime/kotlin/jvm/annotations/JvmPlatformAnnotations.kt +++ b/libraries/stdlib/jvm/runtime/kotlin/jvm/annotations/JvmPlatformAnnotations.kt @@ -18,7 +18,7 @@ import kotlin.reflect.KClass @Target(AnnotationTarget.FUNCTION, AnnotationTarget.CONSTRUCTOR) @Retention(AnnotationRetention.BINARY) @MustBeDocumented -public annotation class JvmOverloads +public actual annotation class JvmOverloads /** * Specifies that an additional static method needs to be generated from this element if it's a function. @@ -30,7 +30,7 @@ public annotation class JvmOverloads @Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER) @Retention(AnnotationRetention.RUNTIME) @MustBeDocumented -public annotation class JvmStatic +public actual annotation class JvmStatic /** * Specifies the name for the Java class or method which is generated from this element. @@ -124,7 +124,7 @@ public actual annotation class JvmField @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.TYPE) @Retention(AnnotationRetention.BINARY) @MustBeDocumented -public annotation class JvmSuppressWildcards(val suppress: Boolean = true) +public actual annotation class JvmSuppressWildcards(actual val suppress: Boolean = true) /** * Instructs compiler to generate wildcard for annotated type arguments corresponding to parameters with declaration-site variance. @@ -134,4 +134,4 @@ public annotation class JvmSuppressWildcards(val suppress: Boolean = true) @Target(AnnotationTarget.TYPE) @Retention(AnnotationRetention.BINARY) @MustBeDocumented -public annotation class JvmWildcard +public actual annotation class JvmWildcard \ No newline at end of file