IO: update ByteReadChannel.cancel/close documentation

Author: Sergey Mashkov

core/kotlinx-coroutines-io/src/main/kotlin/kotlinx/coroutines/experimental/io/ByteReadChannel.kt

@@ -145,6 +145,16 @@ public interface ByteReadChannel {
      */
     suspend fun read(min: Int = 1, block: (ByteBuffer) -> Unit)
 
+    /**
+     * Close channel with optional [cause] cancellation. Unlike [ByteWriteChannel.close] that could close channel
+     * normally, cancel does always close with error so any operations on this channel will always fail
+     * and all suspensions will be resumed with exception.
+     *
+     * Please note that if the channel has been provided by [reader] or [writer] then the corresponding owning
+     * coroutine will be cancelled as well
+     *
+     * @see ByteWriteChannel.close
+     */
     fun cancel(cause: Throwable? = null): Boolean
 }
 

core/kotlinx-coroutines-io/src/main/kotlin/kotlinx/coroutines/experimental/io/ByteWriteChannel.kt

@@ -129,6 +129,10 @@ public interface ByteWriteChannel {
      * all subsequent write operations throw [ClosedWriteChannelException] or the specified [cause].
      * However, [isClosedForRead][ByteReadChannel.isClosedForRead] on the side of [ByteReadChannel]
      * starts returning `true` only after all written bytes have been read.
+     *
+     * Please note that if the channel has been closed with cause and it has been provided by [reader] or [writer]
+     * coroutine then the corresponding coroutine will be cancelled with [cause]. If no [cause] provided then no
+     * cancellation will be propagated.
      */
     public fun close(cause: Throwable? = null): Boolean