Add documentation to parts of scala.concurrent.

4 files changed, 33 insertions, 9 deletions

diff --git a/src/library/scala/concurrent/Channel.scala b/src/library/scala/concurrent/Channel.scala
index 067244bd1c..89ad7d8c0e 100644
--- a/src/library/scala/concurrent/Channel.scala
+++ b/src/library/scala/concurrent/Channel.scala
@@ -10,8 +10,10 @@
 
 package scala.concurrent
 
-/** This class ...
+/** This class provides a simple FIFO queue of data objects,
+ *  which are read by one or more reader threads.
  *
+ *  @tparam A type of data exchanged
  *  @author  Martin Odersky
  *  @version 1.0, 10/03/2003
  */
@@ -20,11 +22,14 @@ class Channel[A] {
     var elem: A = _
     var next: LinkedList[A] = null
   }
-  private var written = new LinkedList[A] // FIFO buffer, realized through
+  private var written = new LinkedList[A] // FIFO queue, realized through
   private var lastWritten = written       // aliasing of a linked list
   private var nreaders = 0
 
-  /**
+  /** Append a value to the FIFO queue to be read by `read`.
+   *  This operation is nonblocking and can be executed by any thread.
+   *
+   * @param x object to enqueue to this channel
    */
   def write(x: A) = synchronized {
     lastWritten.elem = x
@@ -33,6 +38,11 @@ class Channel[A] {
     if (nreaders > 0) notify()
   }
 
+  /** Retrieve the next waiting object from the FIFO queue,
+   *  blocking if necessary until an object is available.
+   *
+   * @return next object dequeued from this channel
+   */
   def read: A = synchronized {
     while (written.next == null) {
       try {
@@ -45,5 +55,4 @@ class Channel[A] {
     written = written.next
     x
   }
-
 }
diff --git a/src/library/scala/concurrent/ExecutionContext.scala b/src/library/scala/concurrent/ExecutionContext.scala
index a1e94c8876..4674c9174b 100644
--- a/src/library/scala/concurrent/ExecutionContext.scala
+++ b/src/library/scala/concurrent/ExecutionContext.scala
@@ -77,12 +77,12 @@ trait ExecutionContext {
 }
 
 /**
- * Union interface since Java does not support union types
+ * An [[ExecutionContext]] that is also a Java [[Executor]].
  */
 trait ExecutionContextExecutor extends ExecutionContext with Executor
 
 /**
- * Union interface since Java does not support union types
+ * An [[ExecutionContext]] that is also a Java [[ExecutorService]].
  */
 trait ExecutionContextExecutorService extends ExecutionContextExecutor with ExecutorService
 
diff --git a/src/library/scala/concurrent/SyncVar.scala b/src/library/scala/concurrent/SyncVar.scala
index d5dc3d7e3f..494c955833 100644
--- a/src/library/scala/concurrent/SyncVar.scala
+++ b/src/library/scala/concurrent/SyncVar.scala
@@ -13,6 +13,7 @@ import java.util.concurrent.TimeUnit
 /** A class to provide safe concurrent access to a mutable cell.
  *  All methods are synchronized.
  *
+ *  @tparam A type of the contained value
  *  @author  Martin Odersky
  *  @version 1.0, 10/03/2003
  */
@@ -20,6 +21,12 @@ class SyncVar[A] {
   private var isDefined: Boolean = false
   private var value: Option[A] = None
 
+  /**
+   * Waits for this SyncVar to become defined and returns
+   * the result, without modifying the stored value.
+   *
+   * @return value that is held in this container
+   */
   def get: A = synchronized {
     while (!isDefined) wait()
     value.get
@@ -57,8 +64,12 @@ class SyncVar[A] {
     value
   }
 
-  /** Waits for this SyncVar to become defined and returns
-   *  the result */
+  /**
+   * Waits for this SyncVar to become defined and returns
+   * the result, unsetting the stored value before returning.
+   *
+   * @return value that was held in this container
+   */
   def take(): A = synchronized {
     try get
     finally unsetVal()
@@ -129,4 +140,3 @@ class SyncVar[A] {
   }
 
 }
-
diff --git a/src/library/scala/concurrent/package.scala b/src/library/scala/concurrent/package.scala
index cc1350f5a9..4d88253de4 100644
--- a/src/library/scala/concurrent/package.scala
+++ b/src/library/scala/concurrent/package.scala
@@ -55,6 +55,11 @@ package object concurrent {
 }
 
 package concurrent {
+  /**
+   * This marker trait is used by [[Await]] to ensure that [[Awaitable.ready]] and [[Awaitable.result]]
+   * are not directly called by user code. An implicit instance of this trait is only available when
+   * user code is currently calling the methods on [[Await]].
+   */
   @implicitNotFound("Don't call `Awaitable` methods directly, use the `Await` object.")
   sealed trait CanAwait