scala.actors: added some more ScalaDoc comments.

8 files changed, 128 insertions, 44 deletions

diff --git a/src/actors/scala/actors/Actor.scala b/src/actors/scala/actors/Actor.scala
index 79ae0e1f83..1da3c683f7 100644
--- a/src/actors/scala/actors/Actor.scala
+++ b/src/actors/scala/actors/Actor.scala
@@ -51,6 +51,19 @@ object Actor {
     a*/
   }
 
+  /**
+   * <p>This function is used for the definition of actors.</p>
+   * <p>The following example demonstrates its usage:</p><pre>
+   * import scala.actors.Actor._
+   * ...
+   * val a = actor {
+   *   ...
+   * }
+   * </pre>
+   *
+   * @param  body  the code block to be executed by the newly created actor
+   * @return       the newly created actor. Note that it is automatically started.
+   */
   def actor(body: => Unit): Actor = synchronized {
     val actor = new Actor {
       def act() = body
@@ -75,6 +88,10 @@ object Actor {
   }
 */
 
+  /**
+   * Receives the next message from the mailbox of the current actor
+   * <code>self</code>.
+   */
   def ? : Any = self.?
 
   /**
@@ -82,8 +99,8 @@ object Actor {
    * <code>self</code>. Blocks if no message matching any of the
    * cases of <code>f</code> can be received.
    *
-   * @param f ...
-   * @return  ...
+   * @param  f a partial function specifying patterns and actions
+   * @return   the result of processing the received message
    */
   def receive[a](f: PartialFunction[Any, a]): a =
     self.receive(f)
@@ -96,36 +113,36 @@ object Actor {
    * received the <code>TIMEOUT</code> action is executed if
    * specified.
    *
-   * @param msec ...
-   * @param f    ...
-   * @return     ...
+   * @param  msec the time span before timeout
+   * @param  f    a partial function specifying patterns and actions
+   * @return      the result of processing the received message
    */
   def receiveWithin[R](msec: long)(f: PartialFunction[Any, R]): R =
     self.receiveWithin(msec)(f)
 
   /**
-   * <code>receive</code> for event-based reactors.
+   * Lightweight variant of <code>receive</code>.
    *
    * Actions in <code>f</code> have to contain the rest of the
    * computation of <code>self</code>, as this method will never
    * return.
    *
-   * @param f ...
-   * @return  ...
+   * @param  f a partial function specifying patterns and actions
+   * @return   this function never returns
    */
   def react(f: PartialFunction[Any, Unit]): Nothing =
     self.react(f)
 
   /**
-   * <code>receiveWithin</code> for event-based reactors.
+   * Lightweight variant of <code>receiveWithin</code>.
    *
    * Actions in <code>f</code> have to contain the rest of the
    * computation of <code>self</code>, as this method will never
    * return.
    *
-   * @param msec ...
-   * @param f    ...
-   * @return     ...
+   * @param  msec the time span before timeout
+   * @param  f    a partial function specifying patterns and actions
+   * @return      this function never returns
    */
   def reactWithin(msec: long)(f: PartialFunction[Any, Unit]): Nothing =
     self.reactWithin(msec)(f)
@@ -172,7 +189,7 @@ object Actor {
    * Causes <code>self</code> to repeatedly execute
    * <code>body</code>.
    *
-   * @param body ...
+   * @param body the code block to be executed
    */
   def loop(body: => Unit): Unit = {
     val s = self
@@ -185,8 +202,8 @@ object Actor {
    * Causes <code>self</code> to execute <code>first</code>
    * followed by <code>next</code>.
    *
-   * @param first ...
-   * @param next  ...
+   * @param first the first code block to be executed
+   * @param next  the second code block to be executed
    */
   def seq[a, b](first: => a, next: => b): Nothing = {
     val s = self
@@ -199,8 +216,8 @@ object Actor {
   /**
    * Links <code>self</code> to actor <code>to</code>.
    *
-   * @param to ...
-   * @return   ...
+   * @param  to the actor to link to
+   * @return
    */
   def link(to: Actor): Actor = self.link(to)
 
@@ -215,7 +232,7 @@ object Actor {
   /**
    * Unlinks <code>self</code> from actor <code>from</code>.
    *
-   * @param from ...
+   * @param from the actor to unlink from
    */
   def unlink(from: Actor): Unit = self.unlink(from)
 
@@ -639,3 +656,35 @@ trait Actor extends OutputChannel[Any] {
  */
 case class Exit(from: Actor, reason: String)
 
+
+/**
+ * <p>This object is used as the timeout pattern in
+ * <code>receiveWithin</code> and <code>reactWithin</code>.
+ * </p>
+ * <p>The following example demonstrates its usage:</p><pre>
+ * receiveWithin(500) {
+ *   case {x, y}  => ...
+ *   case TIMEOUT => ...
+ * }
+ * </pre>
+ *
+ * @version 0.9.2
+ * @author Philipp Haller
+ */
+case object TIMEOUT
+
+
+/**
+ * <p>This class is used to manage control flow of actor
+ * executions.</p>
+ *
+ * @version 0.9.2
+ * @author Philipp Haller
+ */
+private[actors] class SuspendActorException extends Throwable {
+  /*
+   * For efficiency reasons we do not fill in
+   * the execution stack trace.
+   */
+  override def fillInStackTrace(): Throwable = this
+}
diff --git a/src/actors/scala/actors/Channel.scala b/src/actors/scala/actors/Channel.scala
index 7449f9a4eb..cee8ab5642 100644
--- a/src/actors/scala/actors/Channel.scala
+++ b/src/actors/scala/actors/Channel.scala
@@ -10,20 +10,24 @@
 
 package scala.actors
 
-import Actor._
-
-case object TIMEOUT
-
-class SuspendActorException extends Throwable {
-  /*
-   * For efficiency reasons we do not fill in
-   * the execution stack trace.
-   */
-  override def fillInStackTrace(): Throwable = {
-    this
-  }
-}
 
+/** <p>
+ *    This class is used to pattern match on values that were sent
+ *    to some channel <code>Chan<sub>n</sub></code> by the current
+ *    actor <code>self</code>.
+ *  </p>
+ *  <p>
+ *    The following example demonstrates its usage:
+ *  </p><pre>
+ *  receive {
+ *    case Chan1 ! msg1 => ...
+ *    case Chan2 ! msg2 => ...
+ *  }
+ *  </pre>
+ *
+ * @version 0.9.2
+ * @author Philipp Haller
+ */
 case class ! [a](ch: Channel[a], msg: a)
 
 /**
diff --git a/src/actors/scala/actors/InputChannel.scala b/src/actors/scala/actors/InputChannel.scala
index c22671fc93..80f334b30d 100644
--- a/src/actors/scala/actors/InputChannel.scala
+++ b/src/actors/scala/actors/InputChannel.scala
@@ -11,8 +11,10 @@
 package scala.actors
 
 /**
- * The trait <code>InputChannel</code> ...
+ * The <code>InputChannel</code> trait provides a common interface
+ * for all channels from which values can be received.
  *
+ * @version 0.9.2
  * @author Philipp Haller
  */
 trait InputChannel[Msg] {
diff --git a/src/actors/scala/actors/OutputChannel.scala b/src/actors/scala/actors/OutputChannel.scala
index 964c9dada1..50cde1a4fa 100644
--- a/src/actors/scala/actors/OutputChannel.scala
+++ b/src/actors/scala/actors/OutputChannel.scala
@@ -11,8 +11,10 @@
 package scala.actors
 
 /**
- * The trait <code>OutputChannel</code> ...
+ * The <code>OutputChannel</code> trait provides a common interface
+ * for all channels to which values can be sent.
  *
+ * @version 0.9.2
  * @author Philipp Haller
  */
 trait OutputChannel[Msg] {
diff --git a/src/actors/scala/actors/Reaction.scala b/src/actors/scala/actors/Reaction.scala
index 13e2ed7d5e..fd3f8df0e9 100644
--- a/src/actors/scala/actors/Reaction.scala
+++ b/src/actors/scala/actors/Reaction.scala
@@ -13,7 +13,16 @@ package scala.actors
 
 import java.lang.{InterruptedException, Runnable}
 
-class ExitActorException extends Throwable
+/** <p>
+ *    This exception is thrown whenever an actor exits.
+ *    Its purpose is to let <code>exit</code> have
+ *    return type <code>Nothing</code>.
+ *  </p>
+ *
+ * @version 0.9.2
+ * @author Philipp Haller
+ */
+private[actors] class ExitActorException extends Throwable
 
 /**
  * The abstract class <code>Reaction</code> associates
diff --git a/src/actors/scala/actors/Scheduler.scala b/src/actors/scala/actors/Scheduler.scala
index 15852fa7cb..947ad9947d 100644
--- a/src/actors/scala/actors/Scheduler.scala
+++ b/src/actors/scala/actors/Scheduler.scala
@@ -20,8 +20,7 @@ import scala.collection.mutable.{ArrayBuffer, Buffer, HashMap, Queue, Stack, Has
 
 /**
  * The <code>Scheduler</code> object is used by
- * <code>Actor</code> to execute tasks of an execution of a
- * reactor.
+ * <code>Actor</code> to execute tasks of an execution of an actor.
  *
  * @version 0.9.2
  * @author Philipp Haller
@@ -70,7 +69,7 @@ object Scheduler {
 
 /**
  * This abstract class provides a common interface for all
- * schedulers used to execute reactors.
+ * schedulers used to execute actor tasks.
  *
  * @version 0.9.2
  * @author Philipp Haller
@@ -99,7 +98,7 @@ trait IScheduler {
 
 
 /**
- * This scheduler executes the tasks of a reactor on a single
+ * This scheduler executes the tasks of an actor on a single
  * thread (the current thread).
  *
  * @version 0.9.2
@@ -133,16 +132,18 @@ class SingleThreadedScheduler extends IScheduler {
 
 
 /**
- * The <code>QuickException</code> class ...
+ * The <code>QuickException</code> class is used to manage control flow
+ * of certain schedulers and worker threads.
+ *
+ * @version 0.9.2
+ * @author Philipp Haller
  */
-class QuitException extends Throwable {
+private[actors] class QuitException extends Throwable {
   /*
    For efficiency reasons we do not fill in
    the execution stack trace.
    */
-  override def fillInStackTrace(): Throwable = {
-    this
-  }
+  override def fillInStackTrace(): Throwable = this
 }
 
 /**
diff --git a/src/actors/scala/actors/ThreadPoolScheduler.scala b/src/actors/scala/actors/ThreadPoolScheduler.scala
index 2174d90497..eefd9bcbe9 100644
--- a/src/actors/scala/actors/ThreadPoolScheduler.scala
+++ b/src/actors/scala/actors/ThreadPoolScheduler.scala
@@ -13,7 +13,18 @@ import java.util.concurrent.{ThreadPoolExecutor,
                              TimeUnit,
                              RejectedExecutionHandler}
 
-class TaskRejectedHandler(sched: ThreadPoolScheduler) extends RejectedExecutionHandler {
+/**
+ * This handler is called whenever the thread pool of its
+ * associated <code>ThreadPoolScheduler</code> is unable
+ * to serve a request to execute some task.
+ *
+ * This handler executes rejected tasks on the thread of
+ * the scheduler.
+ *
+ * @version 0.9.2
+ * @author Philipp Haller
+ */
+private class TaskRejectedHandler(sched: ThreadPoolScheduler) extends RejectedExecutionHandler {
   def rejectedExecution(r: Runnable, executor: ThreadPoolExecutor) {
     sched.pendReaction
     r.run()
@@ -22,6 +33,9 @@ class TaskRejectedHandler(sched: ThreadPoolScheduler) extends RejectedExecutionH
 }
 
 /**
+ * <p>This scheduler uses a thread pool to execute tasks that are generated
+ * by the execution of actors. This scheduler is only available on Java >= 1.5
+ * since it uses <code>java.util.concurrent.ThreadPoolExecutor</code>.</p>
  *
  * @version 0.9.2
  * @author Philipp Haller
diff --git a/src/actors/scala/actors/TickedScheduler.scala b/src/actors/scala/actors/TickedScheduler.scala
index 333c1aaa63..2d85263b6d 100644
--- a/src/actors/scala/actors/TickedScheduler.scala
+++ b/src/actors/scala/actors/TickedScheduler.scala
@@ -9,6 +9,9 @@ import scala.collection.Set
 import scala.collection.mutable.{ArrayBuffer, Buffer, HashMap, Queue, Stack, HashSet}
 
 /**
+ * <p>This scheduler uses a thread pool to execute tasks that are generated
+ * by the execution of actors. Unlike <code>ThreadPoolScheduler</code>, this
+ * scheduler is available on all Java versions >= 1.4.</p>
  *
  * @version 0.9.2
  * @author Philipp Haller