BroadcastChannel pseudo-constructor is replaced with top-level fun

Author: elizarov

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/ArrayBroadcastChannel.kt

@@ -30,6 +30,8 @@ import kotlin.concurrent.withLock
  * Note, that elements that are sent to the broadcast channel while there are no [openSubscription] subscribers are immediately
  * lost.
  *
+ * This channel is created by `BroadcastChannel(capacity)` factory function invocation.
+ *
  * This implementation uses lock to protect the buffer, which is held only during very short buffer-update operations.
  * The lock at each subscription is also used to manage concurrent attempts to receive from the same subscriber.
  * The lists of suspended senders or receivers are lock-free.

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/BroadcastChannel.kt

@@ -25,29 +25,21 @@ import java.io.Closeable
  * that subscribe for the elements using [openSubscription] function and unsubscribe using [SubscriptionReceiveChannel.close]
  * function.
  *
- * See [BroadcastChannel()][BroadcastChannel.invoke] factory function for the description of available
+ * See `BroadcastChannel()` factory function for the description of available
  * broadcast channel implementations.
  */
 public interface BroadcastChannel<E> : SendChannel<E> {
     /**
      * Factory for broadcast channels.
+     * @suppress **Deprecated**
      */
     public companion object Factory {
         /**
          * Creates a broadcast channel with the specified buffer capacity.
-         *
-         * The resulting channel type depends on the specified [capacity] parameter:
-         * * when `capacity` positive, but less than [UNLIMITED] -- creates [ArrayBroadcastChannel];
-         * * when `capacity` is [CONFLATED] -- creates [ConflatedBroadcastChannel] that conflates back-to-back sends;
-         * * otherwise -- throws [IllegalArgumentException].
+         * @suppress **Deprecated**
          */
-        public operator fun <E> invoke(capacity: Int): BroadcastChannel<E> =
-            when (capacity) {
-                0 -> throw IllegalArgumentException("Unsupported 0 capacity for BroadcastChannel")
-                UNLIMITED -> throw IllegalArgumentException("Unsupported UNLIMITED capacity for BroadcastChannel")
-                CONFLATED -> ConflatedBroadcastChannel()
-                else -> ArrayBroadcastChannel(capacity)
-            }
+        @Deprecated("Replaced with top-level function", level = DeprecationLevel.HIDDEN)
+        public operator fun <E> invoke(capacity: Int): BroadcastChannel<E> = BroadcastChannel(capacity)
     }
 
     /**
@@ -65,6 +57,22 @@ public interface BroadcastChannel<E> : SendChannel<E> {
     public fun open(): SubscriptionReceiveChannel<E> = openSubscription()
 }
 
+/**
+ * Creates a broadcast channel with the specified buffer capacity.
+ *
+ * The resulting channel type depends on the specified [capacity] parameter:
+ * * when `capacity` positive, but less than [UNLIMITED] -- creates [ArrayBroadcastChannel];
+ * * when `capacity` is [CONFLATED] -- creates [ConflatedBroadcastChannel] that conflates back-to-back sends;
+ * * otherwise -- throws [IllegalArgumentException].
+ */
+public fun <E> BroadcastChannel(capacity: Int): BroadcastChannel<E> =
+    when (capacity) {
+        0 -> throw IllegalArgumentException("Unsupported 0 capacity for BroadcastChannel")
+        UNLIMITED -> throw IllegalArgumentException("Unsupported UNLIMITED capacity for BroadcastChannel")
+        CONFLATED -> ConflatedBroadcastChannel()
+        else -> ArrayBroadcastChannel(capacity)
+    }
+
 /**
  * Return type for [BroadcastChannel.openSubscription] that can be used to [receive] elements from the
  * open subscription and to [close] it to unsubscribe.

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/ConflatedBroadcastChannel.kt

@@ -31,6 +31,7 @@ import java.util.concurrent.atomic.AtomicReferenceFieldUpdater
  * Sender to this broadcast channel never suspends and [offer] always returns `true`.
  *
  * A secondary constructor can be used to create an instance of this class that already holds a value.
+ * This channel is also created by `BroadcastChannel(Channel.CONFLATED)` factory function invocation.
  *
  * This implementation is fully lock-free. In this implementation
  * [opening][openSubscription] and [closing][SubscriptionReceiveChannel.close] subscription takes O(N) time, where N is the