Merge branch 'master' into develop

Author: qwwdfsad

README.md

@@ -161,7 +161,7 @@ to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Grad
 ### Requirements
 
 * JDK >= 1.8 referred to by the `JAVA_HOME` environment variable.
-* JDK 1.6 referred to by the `JDK_16` environment variable.
+* JDK 1.6 referred to by the `JDK_16` environment variable. It is okay to have `JDK_16` pointing to `JAVA_HOME` for external contributions.
 
 ## Contributions and releases
 

common/kotlinx-coroutines-core-common/src/channels/Channel.kt

@@ -221,7 +221,7 @@ public interface ReceiveChannel<out E> {
      * [isClosedForReceive] without cause. The [select] invocation fails with
      * the original [close][SendChannel.close] cause exception if the channel has _failed_.
      *
-     * **Note: This is an experimental api.** This function may be replaced with a better on in the future.
+     * **Note: This is an experimental api.** This function may be replaced with a better one in the future.
      */
     @ExperimentalCoroutinesApi
     public val onReceiveOrNull: SelectClause1<E?>

core/kotlinx-coroutines-core/test/guide/example-exceptions-04.kt

@@ -8,7 +8,7 @@ package kotlinx.coroutines.guide.exceptions04
 import kotlinx.coroutines.*
 
 fun main() = runBlocking {
-//sampleEnd
+//sampleStart
     val handler = CoroutineExceptionHandler { _, exception -> 
         println("Caught $exception") 
     }

docs/basics.md

@@ -220,7 +220,7 @@ Instead of launching coroutines in the [GlobalScope], just like we usually do wi
 we can launch coroutines in the specific scope of the operation we are performing. 
 
 In our example, we have `main` function that is turned into a coroutine using [runBlocking] coroutine builder.
-Every coroutine builder, including `runBlocking`, adds an instance of [CoroutineScope] to the scope its code block. 
+Every coroutine builder, including `runBlocking`, adds an instance of [CoroutineScope] to the scope of its code block. 
 We can launch coroutines in this scope without having to `join` them explicitly, because
 an outer coroutine (`runBlocking` in our example) does not complete until all the coroutines launched
 in its scope complete. Thus, we can make our example simpler:

docs/exception-handling.md

@@ -206,7 +206,7 @@ when its child completes with exception despite the installed handler.
 import kotlinx.coroutines.*
 
 fun main() = runBlocking {
-//sampleEnd
+//sampleStart
     val handler = CoroutineExceptionHandler { _, exception -> 
         println("Caught $exception") 
     }

integration/README.md

@@ -8,7 +8,7 @@ Module name below corresponds to the artifact name in Maven/Gradle.
 * [kotlinx-coroutines-jdk8](kotlinx-coroutines-jdk8/README.md) -- integration with JDK8 `CompletableFuture` (Android API level 24).
 * [kotlinx-coroutines-guava](kotlinx-coroutines-guava/README.md) -- integration with Guava [ListenableFuture](https://github.com/google/guava/wiki/ListenableFutureExplained).
 * [kotlinx-coroutines-slf4j](kotlinx-coroutines-slf4j/README.md) -- integration with SLF4J [MDC](https://logback.qos.ch/manual/mdc.html).
-* [kotlinx-coroutines-play-services](kotlinx-coroutines-play-services) -- integration with Google Play Services [Tasks API](https://developers.google.com/android/guides/tasks). |
+* [kotlinx-coroutines-play-services](kotlinx-coroutines-play-services) -- integration with Google Play Services [Tasks API](https://developers.google.com/android/guides/tasks).
 
 ## Contributing
 

integration/kotlinx-coroutines-jdk8/README.md

@@ -39,7 +39,7 @@ fun combineImagesAsync(name1: String, name2: String): CompletableFuture<Image> =
 Note, that this module should be used only for integration with existing Java APIs based on `CompletableFuture`. 
 Writing pure-Kotlin code that uses `CompletableFuture` is highly not recommended, since the resulting APIs based
 on the futures are quite error-prone. See the discussion on 
-[Asynchronous Programming Styles](https://github.com/Kotlin/kotlin-coroutines/blob/master/kotlin-coroutines-informal.md#asynchronous-programming-styles)
+[Asynchronous Programming Styles](https://github.com/Kotlin/KEEP/blob/master/proposals/coroutines.md#asynchronous-programming-styles)
 for details on general problems pertaining to any future-based API and keep in mind that `CompletableFuture` exposes
 a _blocking_ method 
 [get](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Future.html#get--)