Moved documentation for different kinds of channels to Channel interface

Author: elizarov

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

@@ -16,9 +16,10 @@ import kotlinx.coroutines.experimental.selects.*
  *
  * This implementation uses lock to protect the buffer, which is held only during very short buffer-update operations.
  * The lists of suspended senders or receivers are lock-free.
+ * 
  * @suppress **This an internal API and should not be used from general code.**
  */
-@InternalCoroutinesApi // todo: review KDoc refs
+@InternalCoroutinesApi
 public open class ArrayChannel<E>
 @Deprecated(
     "Replace with Channel factory function",

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

@@ -321,7 +321,28 @@ public interface ChannelIterator<out E> {
  * Conceptually, a channel is similar to [BlockingQueue][java.util.concurrent.BlockingQueue],
  * but it has suspending operations instead of blocking ones and it can be closed.
  *
- * See `Channel(capacity)` factory function for the description of available channel implementations.
+ * `Channel(capacity)` factory function is used to create channels of different kind depending on
+ * the value of `capacity` integer:
+ *
+ * * When `capacity` is 0 -- it creates `RendezvousChannel`.
+ *   This channel does not have any buffer at all. An element is transferred from sender
+ *   to receiver only when [send] and [receive] invocations meet in time (rendezvous), so [send] suspends
+ *   until another coroutine invokes [receive] and [receive] suspends until another coroutine invokes [send].
+ *
+ * * When `capacity` is [Channel.UNLIMITED] -- it creates `LinkedListChannel`.
+ *   This is a channel with linked-list buffer of a unlimited capacity (limited only by available memory).
+ *   Sender to this channel never suspends and [offer] always returns `true`.
+ *
+ * * When `capacity` is [Channel.CONFLATED] -- it creates `ConflatedChannel`.
+ *   This channel buffers at most one element and conflates all subsequent `send` and `offer` invocations,
+ *   so that the receiver always gets the most recently sent element.
+ *   Back-to-send sent elements are _conflated_ -- only the the most recently sent element is received,
+ *   while previously sent elements **are lost**.
+ *   Sender to this channel never suspends and [offer] always returns `true`.
+ *
+ * * When `capacity` is positive, but less than [UNLIMITED] -- it creates [ArrayChannel].
+ *   This channel has an array buffer of a fixed `capacity`.
+ *   Sender suspends only when buffer is fully and receiver suspends only when buffer is empty.
  */
 public interface Channel<E> : SendChannel<E>, ReceiveChannel<E> {
     /**
@@ -357,15 +378,10 @@ public fun <E> Channel(): Channel<E> = RendezvousChannel<E>()
 
 /**
  * Creates a channel with the specified buffer capacity (or without a buffer by default).
- *
- * The resulting channel type depends on the specified [capacity] parameter:
- * * when `capacity` is 0 -- creates [RendezvousChannel] without a buffer;
- * * when `capacity` is [Channel.UNLIMITED] -- creates [LinkedListChannel] with buffer of unlimited size;
- * * when `capacity` is [Channel.CONFLATED] -- creates [ConflatedChannel] that conflates back-to-back sends;
- * * when `capacity` is positive, but less than [UNLIMITED] -- creates [ArrayChannel] with a buffer of the specified `capacity`;
- * * otherwise -- throws [IllegalArgumentException].
+ * See [Channel] interface documentation for details.
+ * 
+ * @throws IllegalArgumentException when [capacity] < -1
  */
-// todo: docs
 public fun <E> Channel(capacity: Int = 0): Channel<E> =
     when (capacity) {
         0 -> RendezvousChannel()

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

@@ -20,7 +20,7 @@ import kotlinx.coroutines.experimental.selects.*
  *
  * @suppress **This an internal API and should not be used from general code.**
  */
-@InternalCoroutinesApi // todo: review KDoc usage
+@InternalCoroutinesApi
 public open class ConflatedChannel<E>
 @Deprecated(
     "Replace with Channel factory function",

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

@@ -17,7 +17,7 @@ import kotlinx.coroutines.experimental.selects.*
  *
  * @suppress **This an internal API and should not be used from general code.**
  */
-@InternalCoroutinesApi // todo: review KDoc usage
+@InternalCoroutinesApi
 public open class LinkedListChannel<E>
 @Deprecated(
     "Replace with Channel factory function",

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

@@ -55,12 +55,8 @@ interface ProducerJob<out E> : ReceiveChannel<E>, Job {
  * Uncaught exceptions in this coroutine close the channel with this exception as a cause and
  * 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` is 0 (default) -- uses [RendezvousChannel] without a buffer;
- * * when `capacity` is [Channel.UNLIMITED] -- uses [LinkedListChannel] with buffer of unlimited size;
- * * when `capacity` is [Channel.CONFLATED] -- uses [ConflatedChannel] that conflates back-to-back sends;
- * * when `capacity` is positive, but less than [UNLIMITED] -- uses [ArrayChannel] with a buffer of the specified `capacity`;
- * * otherwise -- throws [IllegalArgumentException].
+ * The kind of the resulting channel depends on the specified [capacity] parameter.
+ * See [Channel] interface documentation for details.
  *
  * See [newCoroutineContext] for a description of debugging facilities that are available for newly created coroutine.
  *

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

@@ -17,7 +17,7 @@ import kotlinx.coroutines.experimental.*
  * 
  * @suppress **This an internal API and should not be used from general code.**
  */
-@InternalCoroutinesApi // todo: review KDoc usage
+@InternalCoroutinesApi
 public open class RendezvousChannel<E>
 @Deprecated(
     "Replace with Channel factory function",

core/kotlinx-coroutines-core/src/channels/Actor.kt

@@ -61,12 +61,8 @@ interface ActorJob<in E> : SendChannel<E> {
  * Uncaught exceptions in this coroutine close the channel with this exception as a cause and
  * the resulting channel becomes _failed_, so that any attempt to send to such a channel throws exception.
  *
- * The kind of the resulting channel depends on the specified [capacity] parameter:
- * * when `capacity` is 0 (default) -- uses [RendezvousChannel] without a buffer;
- * * when `capacity` is [Channel.UNLIMITED] -- uses [LinkedListChannel] with buffer of unlimited size;
- * * when `capacity` is [Channel.CONFLATED] -- uses [ConflatedChannel] that conflates back-to-back sends;
- * * when `capacity` is positive, but less than [UNLIMITED] -- uses [ArrayChannel] with a buffer of the specified `capacity`;
- * * otherwise -- throws [IllegalArgumentException].
+ * The kind of the resulting channel depends on the specified [capacity] parameter.
+ * See [Channel] interface documentation for details.
  *
  * See [newCoroutineContext][CoroutineScope.newCoroutineContext] for a description of debugging facilities that are available for newly created coroutine.
  *

core/kotlinx-coroutines-core/src/channels/TickerChannels.kt

@@ -43,7 +43,7 @@ enum class TickerMode {
  * Creates a channel that produces the first item after the given initial delay and subsequent items with the
  * given delay between them.
  *
- * The resulting channel is a [rendezvous channel][RendezvousChannel]. When receiver from this channel does not keep
+ * The resulting channel is a _rendezvous channel_. When receiver from this channel does not keep
  * up with receiving the elements from this channel, they are not being sent due to backpressure. The actual
  * timing behavior of ticker in this case is controlled by [mode] parameter which
  * is set to [TickerMode.FIXED_PERIOD] by default. See [TickerMode] for other details.