Improve the explanation of how await throws exceptions

Fixes two issues:
* It is surprising for some users that the same exception can be
  thrown several times. Clarified this point explicitly.
* Due to #3658, `await` can throw `CancellationException` in
  several cases: when the `await` call is cancelled, or when the
  `Deferred` is cancelled. This is clarified with an example of
  how to handle this.

Fixes #3937

Author: dkhalanskyjb

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

@@ -33,17 +33,37 @@ import kotlinx.coroutines.selects.*
 public interface Deferred<out T> : Job {
 
     /**
-     * Awaits for completion of this value without blocking a thread and resumes when deferred computation is complete,
-     * returning the resulting value or throwing the corresponding exception if the deferred was cancelled.
+     * Awaits for completion of this value without blocking the thread and returns the resulting value or throws
+     * the exception if the deferred was cancelled.
+     *
+     * Unless cancelled, [await] will return the same result on each invocation:
+     * if the [Deferred] completed successfully, [await] will return the same value every time;
+     * if the [Deferred] completed exceptionally, [await] will rethrow the same exception.
+     *
+     * This suspending function is itself cancellable: if the [Job] of the current coroutine is cancelled or completed
+     * while this suspending function is waiting, this function immediately resumes with [CancellationException].
+     *
+     * This means that [await] can throw [CancellationException] in two cases:
+     * * if the coroutine in which [await] was called got cancelled,
+     * * or if the [Deferred] itself got completed with a [CancellationException].
+     *
+     * In both cases, the [CancellationException] will cancel the coroutine calling [await], unless it's caught.
+     * The following idiom may be helpful to avoid this:
+     * ```
+     * try {
+     *    deferred.await()
+     * } catch (e: CancellationException) {
+     *    currentCoroutineContext().ensureActive() // throws if the current coroutine was cancelled
+     *    processException(e) // if this line executes, the exception is the result of `await` itself
+     * }
+     * ```
      *
-     * This suspending function is cancellable.
-     * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
-     * immediately resumes with [CancellationException].
      * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
      * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details.
      *
-     * This function can be used in [select] invocation with [onAwait] clause.
-     * Use [isCompleted] to check for completion of this deferred value without waiting.
+     * This function can be used in [select] invocations with an [onAwait] clause.
+     * Use [isCompleted] to check for completion of this deferred value without waiting, and
+     * [join] to wait for completion without returning the result.
      */
     public suspend fun await(): T