Introduce guidance functions explaining 'launch' and 'async' usage (#4331)

Fixes KTIJ-13441

Author: dkhalanskyjb

kotlinx-coroutines-core/api/kotlinx-coroutines-core.api

@@ -378,6 +378,13 @@ public final class kotlinx/coroutines/GlobalScope : kotlinx/coroutines/Coroutine
 	public fun getCoroutineContext ()Lkotlin/coroutines/CoroutineContext;
 }
 
+public final class kotlinx/coroutines/GuidanceKt {
+	public static final fun async (Lkotlin/coroutines/CoroutineContext;Lkotlinx/coroutines/CoroutineStart;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/Deferred;
+	public static synthetic fun async$default (Lkotlin/coroutines/CoroutineContext;Lkotlinx/coroutines/CoroutineStart;Lkotlin/jvm/functions/Function2;ILjava/lang/Object;)Lkotlinx/coroutines/Deferred;
+	public static final fun launch (Lkotlin/coroutines/CoroutineContext;Lkotlinx/coroutines/CoroutineStart;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/Job;
+	public static synthetic fun launch$default (Lkotlin/coroutines/CoroutineContext;Lkotlinx/coroutines/CoroutineStart;Lkotlin/jvm/functions/Function2;ILjava/lang/Object;)Lkotlinx/coroutines/Job;
+}
+
 public abstract interface annotation class kotlinx/coroutines/InternalCoroutinesApi : java/lang/annotation/Annotation {
 }
 

kotlinx-coroutines-core/api/kotlinx-coroutines-core.klib.api

@@ -925,6 +925,7 @@ final fun <#A: kotlin/Any?> kotlinx.coroutines.flow/flowOf(kotlin/Array<out #A>.
 final fun <#A: kotlin/Any?> kotlinx.coroutines.flow/merge(kotlin/Array<out kotlinx.coroutines.flow/Flow<#A>>...): kotlinx.coroutines.flow/Flow<#A> // kotlinx.coroutines.flow/merge|merge(kotlin.Array<out|kotlinx.coroutines.flow.Flow<0:0>>...){0§<kotlin.Any?>}[0]
 final fun <#A: kotlin/Any?> kotlinx.coroutines/CompletableDeferred(#A): kotlinx.coroutines/CompletableDeferred<#A> // kotlinx.coroutines/CompletableDeferred|CompletableDeferred(0:0){0§<kotlin.Any?>}[0]
 final fun <#A: kotlin/Any?> kotlinx.coroutines/CompletableDeferred(kotlinx.coroutines/Job? = ...): kotlinx.coroutines/CompletableDeferred<#A> // kotlinx.coroutines/CompletableDeferred|CompletableDeferred(kotlinx.coroutines.Job?){0§<kotlin.Any?>}[0]
+final fun <#A: kotlin/Any?> kotlinx.coroutines/async(kotlin.coroutines/CoroutineContext = ..., kotlinx.coroutines/CoroutineStart = ..., kotlin.coroutines/SuspendFunction1<kotlinx.coroutines/CoroutineScope, #A>): kotlinx.coroutines/Deferred<#A> // kotlinx.coroutines/async|async(kotlin.coroutines.CoroutineContext;kotlinx.coroutines.CoroutineStart;kotlin.coroutines.SuspendFunction1<kotlinx.coroutines.CoroutineScope,0:0>){0§<kotlin.Any?>}[0]
 final fun kotlinx.coroutines.channels/consumesAll(kotlin/Array<out kotlinx.coroutines.channels/ReceiveChannel<*>>...): kotlin/Function1<kotlin/Throwable?, kotlin/Unit> // kotlinx.coroutines.channels/consumesAll|consumesAll(kotlin.Array<out|kotlinx.coroutines.channels.ReceiveChannel<*>>...){}[0]
 final fun kotlinx.coroutines.sync/Mutex(kotlin/Boolean = ...): kotlinx.coroutines.sync/Mutex // kotlinx.coroutines.sync/Mutex|Mutex(kotlin.Boolean){}[0]
 final fun kotlinx.coroutines.sync/Semaphore(kotlin/Int, kotlin/Int = ...): kotlinx.coroutines.sync/Semaphore // kotlinx.coroutines.sync/Semaphore|Semaphore(kotlin.Int;kotlin.Int){}[0]
@@ -936,6 +937,7 @@ final fun kotlinx.coroutines/MainScope(): kotlinx.coroutines/CoroutineScope // k
 final fun kotlinx.coroutines/SupervisorJob(kotlinx.coroutines/Job? = ...): kotlinx.coroutines/CompletableJob // kotlinx.coroutines/SupervisorJob|SupervisorJob(kotlinx.coroutines.Job?){}[0]
 final fun kotlinx.coroutines/SupervisorJob0(kotlinx.coroutines/Job? = ...): kotlinx.coroutines/Job // kotlinx.coroutines/SupervisorJob0|SupervisorJob0(kotlinx.coroutines.Job?){}[0]
 final fun kotlinx.coroutines/handleCoroutineException(kotlin.coroutines/CoroutineContext, kotlin/Throwable) // kotlinx.coroutines/handleCoroutineException|handleCoroutineException(kotlin.coroutines.CoroutineContext;kotlin.Throwable){}[0]
+final fun kotlinx.coroutines/launch(kotlin.coroutines/CoroutineContext = ..., kotlinx.coroutines/CoroutineStart = ..., kotlin.coroutines/SuspendFunction1<kotlinx.coroutines/CoroutineScope, kotlin/Unit>): kotlinx.coroutines/Job // kotlinx.coroutines/launch|launch(kotlin.coroutines.CoroutineContext;kotlinx.coroutines.CoroutineStart;kotlin.coroutines.SuspendFunction1<kotlinx.coroutines.CoroutineScope,kotlin.Unit>){}[0]
 final inline fun <#A: kotlin/Any?, #B: kotlin/Any> (kotlinx.coroutines.flow/Flow<#A>).kotlinx.coroutines.flow/mapNotNull(crossinline kotlin.coroutines/SuspendFunction1<#A, #B?>): kotlinx.coroutines.flow/Flow<#B> // kotlinx.coroutines.flow/mapNotNull|[email protected]<0:0>(kotlin.coroutines.SuspendFunction1<0:0,0:1?>){0§<kotlin.Any?>;1§<kotlin.Any>}[0]
 final inline fun <#A: kotlin/Any?, #B: kotlin/Any?> (kotlinx.coroutines.channels/BroadcastChannel<#A>).kotlinx.coroutines.channels/consume(kotlin/Function1<kotlinx.coroutines.channels/ReceiveChannel<#A>, #B>): #B // kotlinx.coroutines.channels/consume|[email protected]<0:0>(kotlin.Function1<kotlinx.coroutines.channels.ReceiveChannel<0:0>,0:1>){0§<kotlin.Any?>;1§<kotlin.Any?>}[0]
 final inline fun <#A: kotlin/Any?, #B: kotlin/Any?> (kotlinx.coroutines.channels/ReceiveChannel<#A>).kotlinx.coroutines.channels/consume(kotlin/Function1<kotlinx.coroutines.channels/ReceiveChannel<#A>, #B>): #B // kotlinx.coroutines.channels/consume|[email protected]<0:0>(kotlin.Function1<kotlinx.coroutines.channels.ReceiveChannel<0:0>,0:1>){0§<kotlin.Any?>;1§<kotlin.Any?>}[0]

kotlinx-coroutines-core/common/src/Guidance.kt

@@ -0,0 +1,38 @@
+package kotlinx.coroutines
+
+import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.EmptyCoroutineContext
+
+/**
+ * @suppress this is a function that should help users who are trying to use 'launch'
+ * without the corresponding coroutine scope. It is not supposed to be called.
+ */
+@Deprecated("'launch' can not be called without the corresponding coroutine scope. " +
+    "Consider wrapping 'launch' in 'coroutineScope { }', using 'runBlocking { }', " +
+    "or using some other 'CoroutineScope'", level = DeprecationLevel.ERROR)
+@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
+@kotlin.internal.LowPriorityInOverloadResolution
+public fun launch(
+    context: CoroutineContext = EmptyCoroutineContext,
+    start: CoroutineStart = CoroutineStart.DEFAULT,
+    block: suspend CoroutineScope.() -> Unit
+): Job {
+    throw UnsupportedOperationException("Should never be called, was introduced to help with incomplete code")
+}
+
+/**
+ * @suppress this is a function that should help users who are trying to use 'launch'
+ * without the corresponding coroutine scope. It is not supposed to be called.
+ */
+@Deprecated("'async' can not be called without the corresponding coroutine scope. " +
+    "Consider wrapping 'async' in 'coroutineScope { }', using 'runBlocking { }', " +
+    "or using some other 'CoroutineScope'", level = DeprecationLevel.ERROR)
+@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
+@kotlin.internal.LowPriorityInOverloadResolution
+public fun <T> async(
+    context: CoroutineContext = EmptyCoroutineContext,
+    start: CoroutineStart = CoroutineStart.DEFAULT,
+    block: suspend CoroutineScope.() -> T
+): Deferred<T> {
+    throw UnsupportedOperationException("Should never be called, was introduced to help with incomplete code")
+}