Introduce OptionalExpectation for annotations missing on some platforms

This commits adds a new annotation OptionalExpectation to the standard
library, which is experimental. To enable its usage, either pass
'-Xuse-experimental=kotlin.ExperimentalMultiplatform' as a compiler
argument, or '-Xuse-experimental=kotlin.Experimental' and also annotate
each usage with `@UseExperimental(ExperimentalMultiplatform::class)`

 #KT-18882 Fixed

libraries/stdlib/common/src/kotlin/annotations/Annotations.kt

@@ -0,0 +1,40 @@
+/*
+ * 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
+
+import kotlin.annotation.AnnotationTarget.*
+import kotlin.internal.RequireKotlin
+import kotlin.internal.RequireKotlinVersionKind
+
+@Experimental
+@Target(
+    CLASS,
+    ANNOTATION_CLASS,
+    PROPERTY,
+    FIELD,
+    LOCAL_VARIABLE,
+    VALUE_PARAMETER,
+    CONSTRUCTOR,
+    FUNCTION,
+    PROPERTY_GETTER,
+    PROPERTY_SETTER,
+    TYPEALIAS
+)
+@Retention(AnnotationRetention.BINARY)
+@RequireKotlin("1.2.50", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)
+public annotation class ExperimentalMultiplatform
+
+/**
+ * This annotation is only applicable to `expect` annotation classes in multi-platform projects and marks that class as "optional".
+ * Optional expected class is allowed to have no corresponding actual class on the platform. Optional annotations can only be used
+ * to annotate something, not as types in signatures. If an optional annotation has no corresponding actual class on a platform,
+ * the annotation entries where it's used are simply erased when compiling code on that platform.
+ */
+@Target(ANNOTATION_CLASS)
+@Retention(AnnotationRetention.BINARY)
+@ExperimentalMultiplatform
+@RequireKotlin("1.2.50", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)
+public annotation class OptionalExpectation