More kdocs

Author: elizarov

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineDispatcher.kt

@@ -51,7 +51,10 @@ public abstract class CoroutineDispatcher :
      */
     public abstract fun dispatch(context: CoroutineContext, block: Runnable)
 
-    override fun <T> interceptContinuation(continuation: Continuation<T>): Continuation<T> =
+    /**
+     * Returns continuation that wraps the original [continuation], thus intercepting all resumptions.
+     */
+    public override fun <T> interceptContinuation(continuation: Continuation<T>): Continuation<T> =
             DispatchedContinuation(this, continuation)
 
     /**

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineExceptionHandler.kt

@@ -48,6 +48,14 @@ fun handleCoroutineException(context: CoroutineContext, exception: Throwable) {
  * See [handleCoroutineException].
  */
 public interface CoroutineExceptionHandler : CoroutineContext.Element {
+    /**
+     * Key for [CoroutineExceptionHandler] instance in the coroutine context.
+     */
     companion object Key : CoroutineContext.Key<CoroutineExceptionHandler>
+
+    /**
+     * Handles uncaught [exception] in the given [context]. It is invoked
+     * only when everything else fails. See [handleCoroutineException].
+     */
     public fun handleException(context: CoroutineContext, exception: Throwable)
 }

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineName.kt

@@ -23,7 +23,19 @@ import kotlin.coroutines.experimental.CoroutineContext
  * User-specified name of coroutine. This name is used in debugging mode.
  * See [newCoroutineContext] for the description of coroutine debugging facilities.
  */
-public data class CoroutineName(val name: String) : AbstractCoroutineContextElement(CoroutineName) {
+public data class CoroutineName(
+    /**
+     * User-defined coroutine name.
+     */
+    val name: String
+) : AbstractCoroutineContextElement(CoroutineName) {
+    /**
+     * Key for [CoroutineName] instance in the coroutine context.
+     */
     public companion object Key : CoroutineContext.Key<CoroutineName>
+
+    /**
+     * Returns a string representation of the object.
+     */
     override fun toString(): String = "CoroutineName($name)"
 }

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

@@ -30,8 +30,19 @@ public abstract class AbstractChannel<E> : Channel<E> {
 
     // ------ extension points for buffered channels ------
 
+    /**
+     * Returns `true` if this channel has buffer.
+     */
     protected abstract val hasBuffer: Boolean
+
+    /**
+     * Returns `true` if this channel's buffer is empty.
+     */
     protected abstract val isBufferEmpty: Boolean
+
+    /**
+     * Returns `true` if this channel's buffer is full.
+     */
     protected abstract val isBufferFull: Boolean
 
     /**
@@ -49,7 +60,14 @@ public abstract class AbstractChannel<E> : Channel<E> {
 
     // ------ state functions for concrete implementations ------
 
+    /**
+     * Returns non-null closed token if it is first in the queue.
+     */
     protected val closedForReceive: Any? get() = queue.next() as? Closed<*>
+
+    /**
+     * Returns non-null closed token if it is last in the queue.
+     */
     protected val closedForSend: Any? get() = queue.prev() as? Closed<*>
 
     // ------ SendChannel ------
@@ -117,6 +135,9 @@ public abstract class AbstractChannel<E> : Channel<E> {
         }
     }
 
+    /**
+     * Retrieves first receiving waiter from the queue or returns closed token.
+     */
     protected fun takeFirstReceiveOrPeekClosed(): ReceiveOrClosed<E>? =
         queue.removeFirstIfIsInstanceOfOrPeekIf<ReceiveOrClosed<E>> { it is Closed<*> }
 
@@ -219,6 +240,9 @@ public abstract class AbstractChannel<E> : Channel<E> {
 
     override fun iterator(): ChannelIterator<E> = Iterator(this)
 
+    /**
+     * Retrieves first sending waiter from the queue or returns closed token.
+     */
     protected fun takeFirstSendOrPeekClosed(): Send? =
         queue.removeFirstIfIsInstanceOfOrPeekIf<Send> { it is Closed<*> }
 
@@ -297,12 +321,18 @@ public abstract class AbstractChannel<E> : Channel<E> {
         }
     }
 
+    /**
+     * Represents sending waiter in the queue.
+     */
     protected interface Send {
         val pollResult: Any? // E | Closed
         fun tryResumeSend(): Any?
         fun completeResumeSend(token: Any)
     }
 
+    /**
+     * Represents receiver waiter in the queue or closed token.
+     */
     protected interface ReceiveOrClosed<in E> {
         val offerResult: Any // OFFER_SUCCESS | Closed
         fun tryResumeReceive(value: E): Any?

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

@@ -25,7 +25,12 @@ import java.util.concurrent.locks.ReentrantLock
  * 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.
  */
-public class ArrayChannel<E>(val capacity: Int) : AbstractChannel<E>() {
+public class ArrayChannel<E>(
+    /**
+     * Buffer capacity.
+     */
+    val capacity: Int
+) : AbstractChannel<E>() {
     init {
         check(capacity >= 1) { "ArrayChannel capacity must be at least 1, but $capacity was specified" }
     }