Introduce platform specific annotations as optional in common stdlib

#KT-24478

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",

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)

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<out T>` 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()
+@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()

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"

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)
+public annotation class JsQualifier(val value: String)

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

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"

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
+public actual annotation class Synchronized

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