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

compiler/testData/multiplatform/optionalExpectation/common.kt

@@ -0,0 +1,10 @@
+// WITH_RUNTIME
+// ADDITIONAL_COMPILER_ARGUMENTS: -Xuse-experimental=kotlin.ExperimentalMultiplatform
+
+@OptionalExpectation
+expect annotation class A()
+
+expect class C {
+    @A
+    fun f()
+}

compiler/testData/multiplatform/optionalExpectation/js.kt

@@ -0,0 +1,3 @@
+actual class C {
+    actual fun f() {}
+}

compiler/testData/multiplatform/optionalExpectation/jvm.kt

@@ -0,0 +1,6 @@
+actual annotation class A
+
+actual class C {
+    @A
+    actual fun f() {}
+}

compiler/testData/multiplatform/optionalExpectation/output.txt

@@ -0,0 +1,12 @@
+-- Common --
+Exit code: OK
+Output:
+
+-- JVM --
+Exit code: OK
+Output:
+
+-- JS --
+Exit code: OK
+Output:
+

compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt

@@ -0,0 +1,20 @@
+// WITH_RUNTIME
+// ADDITIONAL_COMPILER_ARGUMENTS: -Xuse-experimental=kotlin.ExperimentalMultiplatform
+
+@OptionalExpectation
+expect annotation class A()
+
+fun useInSignature(a: A) = a.toString()
+
+@OptionalExpectation
+expect class NotAnAnnotationClass
+
+@OptionalExpectation
+annotation class NotAnExpectedClass
+
+
+
+annotation class InOtherAnnotation(val a: A)
+
+@InOtherAnnotation(A())
+fun useInOtherAnnotation() {}

compiler/testData/multiplatform/optionalExpectationIncorrectUse/jvm.kt

@@ -0,0 +1,6 @@
+fun useInReturnType(): A? = null
+
+annotation class AnotherAnnotation(val a: A)
+
+@AnotherAnnotation(A())
+fun useInAnotherAnnotation() {}

compiler/testData/multiplatform/optionalExpectationIncorrectUse/output.txt

@@ -0,0 +1,46 @@
+-- Common --
+Exit code: COMPILATION_ERROR
+Output:
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt:7:23: error: declaration annotated with '@OptionalExpectation' can only be used inside an annotation entry
+fun useInSignature(a: A) = a.toString()
+                      ^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt:9:1: error: this annotation is not applicable to target 'class'
+@OptionalExpectation
+^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt:12:1: error: '@OptionalExpectation' can only be used on an expected annotation class
+@OptionalExpectation
+^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt:17:43: error: declaration annotated with '@OptionalExpectation' can only be used inside an annotation entry
+annotation class InOtherAnnotation(val a: A)
+                                          ^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt:19:20: error: declaration annotated with '@OptionalExpectation' can only be used inside an annotation entry
+@InOtherAnnotation(A())
+                   ^
+
+-- JVM --
+Exit code: COMPILATION_ERROR
+Output:
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt:7:23: error: declaration annotated with '@OptionalExpectation' can only be used inside an annotation entry
+fun useInSignature(a: A) = a.toString()
+                      ^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt:9:1: error: this annotation is not applicable to target 'class'
+@OptionalExpectation
+^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt:12:1: error: '@OptionalExpectation' can only be used on an expected annotation class
+@OptionalExpectation
+^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt:17:43: error: declaration annotated with '@OptionalExpectation' can only be used inside an annotation entry
+annotation class InOtherAnnotation(val a: A)
+                                          ^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/common.kt:19:20: error: declaration annotated with '@OptionalExpectation' can only be used inside an annotation entry
+@InOtherAnnotation(A())
+                   ^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/jvm.kt:1:24: error: declaration annotated with '@OptionalExpectation' can only be used inside an annotation entry
+fun useInReturnType(): A? = null
+                       ^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/jvm.kt:3:43: error: declaration annotated with '@OptionalExpectation' can only be used inside an annotation entry
+annotation class AnotherAnnotation(val a: A)
+                                          ^
+compiler/testData/multiplatform/optionalExpectationIncorrectUse/jvm.kt:5:20: error: declaration annotated with '@OptionalExpectation' can only be used inside an annotation entry
+@AnotherAnnotation(A())
+                   ^