From 266d7c15fec79b37420c94e9ca21af8dbc4d8e46 Mon Sep 17 00:00:00 2001
From: Roman Elizarov <elizarov@gmail.com>
Date: Mon, 27 Feb 2017 16:39:28 +0300
Subject: [PATCH] Documentation for createCoroutine/createCoroutineUnchecked

---
 .../experimental/CoroutinesLibrary.kt         |  8 ++++++--
 .../experimental/intrinsics/Intrinsics.kt     | 20 +++++++++++++++++++
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/libraries/stdlib/src/kotlin/coroutines/experimental/CoroutinesLibrary.kt b/libraries/stdlib/src/kotlin/coroutines/experimental/CoroutinesLibrary.kt
index 733a0ad4130..de637eda5d8 100644
--- a/libraries/stdlib/src/kotlin/coroutines/experimental/CoroutinesLibrary.kt
+++ b/libraries/stdlib/src/kotlin/coroutines/experimental/CoroutinesLibrary.kt
@@ -49,10 +49,12 @@ public fun <T> (suspend  () -> T).startCoroutine(
 }
 
 /**
- * Creates coroutine with receiver type [R] and result type [T].
+ * Creates a coroutine with receiver type [R] and result type [T].
  * This function creates a new, fresh instance of suspendable computation every time it is invoked.
+ *
  * To start executing the created coroutine, invoke `resume(Unit)` on the returned [Continuation] instance.
  * The [completion] continuation is invoked when coroutine completes with result or exception.
+ * Repeated invocation of any resume function on the resulting continuation produces [IllegalStateException].
  */
 @SinceKotlin("1.1")
 @Suppress("UNCHECKED_CAST")
@@ -62,10 +64,12 @@ public fun <R, T> (suspend R.() -> T).createCoroutine(
 ): Continuation<Unit> = SafeContinuation(createCoroutineUnchecked(receiver, completion), COROUTINE_SUSPENDED)
 
 /**
- * Creates coroutine without receiver and with result type [T].
+ * Creates a coroutine without receiver and with result type [T].
  * This function creates a new, fresh instance of suspendable computation every time it is invoked.
+ *
  * To start executing the created coroutine, invoke `resume(Unit)` on the returned [Continuation] instance.
  * The [completion] continuation is invoked when coroutine completes with result or exception.
+ * Repeated invocation of any resume function on the resulting continuation produces [IllegalStateException].
  */
 @SinceKotlin("1.1")
 @Suppress("UNCHECKED_CAST")
diff --git a/libraries/stdlib/src/kotlin/coroutines/experimental/intrinsics/Intrinsics.kt b/libraries/stdlib/src/kotlin/coroutines/experimental/intrinsics/Intrinsics.kt
index aa2d221bad9..b463c9924bb 100644
--- a/libraries/stdlib/src/kotlin/coroutines/experimental/intrinsics/Intrinsics.kt
+++ b/libraries/stdlib/src/kotlin/coroutines/experimental/intrinsics/Intrinsics.kt
@@ -52,6 +52,16 @@ public val COROUTINE_SUSPENDED: Any = Any()
 
 // JVM declarations
 
+/**
+ * Creates a coroutine without receiver and with result type [T].
+ * This function creates a new, fresh instance of suspendable computation every time it is invoked.
+ *
+ * To start executing the created coroutine, invoke `resume(Unit)` on the returned [Continuation] instance.
+ * The [completion] continuation is invoked when coroutine completes with result or exception.
+ *
+ * This function is _unchecked_. Repeated invocation of any resume function on the resulting continuation corrupts the
+ * state machine of the coroutine and may result in arbitrary behaviour or exception.
+ */
 @SinceKotlin("1.1")
 @kotlin.jvm.JvmVersion
 public fun <T> (suspend () -> T).createCoroutineUnchecked(
@@ -64,6 +74,16 @@ public fun <T> (suspend () -> T).createCoroutineUnchecked(
         else
             (this.create(completion) as kotlin.coroutines.experimental.jvm.internal.CoroutineImpl).facade
 
+/**
+ * Creates a coroutine with receiver type [R] and result type [T].
+ * This function creates a new, fresh instance of suspendable computation every time it is invoked.
+ *
+ * To start executing the created coroutine, invoke `resume(Unit)` on the returned [Continuation] instance.
+ * The [completion] continuation is invoked when coroutine completes with result or exception.
+ *
+ * This function is _unchecked_. Repeated invocation of any resume function on the resulting continuation corrupts the
+ * state machine of the coroutine and may result in arbitrary behaviour or exception.
+ */
 @SinceKotlin("1.1")
 @kotlin.jvm.JvmVersion
 public fun <R, T> (suspend R.() -> T).createCoroutineUnchecked(