Clarify capacity parameter in broadcast builders

Addresses #815

Author: qwwdfsad

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

@@ -13,7 +13,12 @@ import kotlin.coroutines.*
 /**
  * Broadcasts all elements of the channel.
  *
- * @param capacity capacity of the channel's buffer (1 by default).
+ * The kind of the resulting channel depends on the specified [capacity] parameter:
+ * when `capacity` is positive (1 by default), but less than [UNLIMITED] -- uses `ArrayBroadcastChannel` with a buffer of given capacity,
+ * when `capacity` is [CONFLATED] -- uses [ConflatedBroadcastChannel] that conflates back-to-back sends;
+ *   Note that resulting channel behaves like [ConflatedBroadcastChannel] but is not an instance of [ConflatedBroadcastChannel].
+ *   otherwise -- throws [IllegalArgumentException].
+ *
  * @param start coroutine start option. The default value is [CoroutineStart.LAZY].
  */
 fun <E> ReceiveChannel<E>.broadcast(
@@ -45,8 +50,9 @@ fun <E> ReceiveChannel<E>.broadcast(
  * the resulting channel becomes _failed_, so that any attempt to receive from such a channel throws exception.
  *
  * The kind of the resulting channel depends on the specified [capacity] parameter:
- * * when `capacity` positive (1 by default), but less than [UNLIMITED] -- uses `ArrayBroadcastChannel` with a buffer of given capacity,
+ * * when `capacity` is positive (1 by default), but less than [UNLIMITED] -- uses `ArrayBroadcastChannel` with a buffer of given capacity,
  * * when `capacity` is [CONFLATED] -- uses [ConflatedBroadcastChannel] that conflates back-to-back sends;
+ *   Note that resulting channel behaves like [ConflatedBroadcastChannel] but is not an instance of [ConflatedBroadcastChannel].
  * * otherwise -- throws [IllegalArgumentException].
  *
  * **Note:** By default, the coroutine does not start until the first subscriber appears via [BroadcastChannel.openSubscription]

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

@@ -2,12 +2,13 @@
  * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
+@file:Suppress("FunctionName")
+
 package kotlinx.coroutines.channels
 
 import kotlinx.coroutines.*
 import kotlinx.coroutines.channels.Channel.Factory.CONFLATED
 import kotlinx.coroutines.channels.Channel.Factory.UNLIMITED
-import kotlinx.coroutines.internal.*
 
 /**
  * Broadcast channel is a non-blocking primitive for communication between the sender and multiple receivers