From 23414496c442f88fb5231a7ae0faa3abd0edb086 Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Fri, 24 Apr 2020 02:48:31 +0300
Subject: [PATCH] Annotation to enable overload resolution by lambda return
 type

#KT-38480
---
 .../src/kotlin/annotations/Inference.kt       | 34 ++++++++++++++++++-
 .../kotlin-stdlib-runtime-merged.txt          |  3 ++
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/libraries/stdlib/src/kotlin/annotations/Inference.kt b/libraries/stdlib/src/kotlin/annotations/Inference.kt
index 5074baec711..bb40746481d 100644
--- a/libraries/stdlib/src/kotlin/annotations/Inference.kt
+++ b/libraries/stdlib/src/kotlin/annotations/Inference.kt
@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2018 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -35,3 +35,35 @@ import kotlin.experimental.ExperimentalTypeInference
 @SinceKotlin("1.3")
 @ExperimentalTypeInference
 public annotation class BuilderInference
+
+
+/**
+ * Enables overload selection based on the type of the value returned from lambda argument.
+ *
+ * When two or more function overloads have otherwise the same parameter lists that differ only in the return type
+ * of a functional parameter, this annotation enables overload selection by the type of the value returned from
+ * the lambda function passed to this functional parameter.
+ *
+ * Example:
+ * ```
+ * @OverloadResolutionByLambdaReturnType
+ * fun create(intProducer: () -> Int): Int
+ *
+ * fun create(doubleProducer: () -> Double): Double
+ *
+ * val newValue = create { 3.14 }
+ * ```
+ *
+ * The annotation being applied to one of overloads allows to resolve this ambiguity by analyzing what value is returned
+ * from the lambda function.
+ *
+ * This annotation is also used to discriminate the annotated overloads in case if overload selection still cannot
+ * choose one of them even taking in account the result of lambda parameter analysis. In that case a warning is reported.
+ *
+ * Note: this annotation is experimental, see [ExperimentalTypeInference] on how to opt-in for it.
+ */
+@Target(FUNCTION)
+@Retention(AnnotationRetention.BINARY)
+@SinceKotlin("1.4")
+@ExperimentalTypeInference
+public annotation class OverloadResolutionByLambdaReturnType
\ No newline at end of file
diff --git a/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt b/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt
index 87dc22ae928..5fd0f25d182 100644
--- a/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt
+++ b/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt
@@ -156,6 +156,9 @@ public abstract interface annotation class kotlin/OptIn : java/lang/annotation/A
 public abstract interface annotation class kotlin/OptionalExpectation : java/lang/annotation/Annotation {
 }
 
+public abstract interface annotation class kotlin/OverloadResolutionByLambdaReturnType : java/lang/annotation/Annotation {
+}
+
 public final class kotlin/Pair : java/io/Serializable {
 	public fun <init> (Ljava/lang/Object;Ljava/lang/Object;)V
 	public final fun component1 ()Ljava/lang/Object;