Completed scaladoc for Reactor and Combinators.

4 files changed, 35 insertions, 34 deletions

diff --git a/src/actors/scala/actors/Actor.scala b/src/actors/scala/actors/Actor.scala
index 491c1eb075..c2c967fe69 100644
--- a/src/actors/scala/actors/Actor.scala
+++ b/src/actors/scala/actors/Actor.scala
@@ -382,6 +382,8 @@ object Actor extends Combinators {
  * </ul>
  *
  * @author Philipp Haller
+ *
+ * @define actor actor
  */
 @serializable @SerialVersionUID(-781154067877019505L)
 trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
@@ -605,9 +607,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
     _state == Actor.State.Terminated
   }
 
-  /**
-   * Starts this actor.
-   */
   override def start(): Actor = synchronized {
     if (_state == Actor.State.New) {
       _state = Actor.State.Runnable
diff --git a/src/actors/scala/actors/Combinators.scala b/src/actors/scala/actors/Combinators.scala
index 3c0be7ed15..6082f92323 100644
--- a/src/actors/scala/actors/Combinators.scala
+++ b/src/actors/scala/actors/Combinators.scala
@@ -12,28 +12,35 @@ package scala.actors
 
 private[actors] trait Combinators {
 
+  /**
+   * Enables the composition of suspendable closures using `andThen`,
+   * `loop`, `loopWhile`, etc.
+   */
   implicit def mkBody[a](body: => a): Actor.Body[a]
 
   /**
-   * Causes <code>self</code> to repeatedly execute
-   * <code>body</code>.
+   * Repeatedly executes `body`.
    *
-   * @param body the code block to be executed
+   * @param body the block to be executed
    */
   def loop(body: => Unit): Unit = body andThen loop(body)
 
   /**
-   * Causes <code>self</code> to repeatedly execute
-   * <code>body</code> while the condition
-   * <code>cond</code> is <code>true</code>.
+   * Repeatedly executes `body` while the condition `cond` is `true`.
    *
    * @param cond the condition to test
-   * @param body the code block to be executed
+   * @param body the block to be executed
    */
   def loopWhile(cond: => Boolean)(body: => Unit): Unit =
     if (cond) { body andThen loopWhile(cond)(body) }
     else continue
 
+  /**
+   * Continues with the execution of the closure registered as
+   * continuation following `andThen`. Continues with the execution
+   * of the next loop iteration when invoked inside the body of `loop`
+   * or `loopWhile`.
+   */
   def continue: Unit = throw new KillActorControl
 
 }
diff --git a/src/actors/scala/actors/OutputChannel.scala b/src/actors/scala/actors/OutputChannel.scala
index 514c445944..8bf92b448e 100644
--- a/src/actors/scala/actors/OutputChannel.scala
+++ b/src/actors/scala/actors/OutputChannel.scala
@@ -15,18 +15,18 @@ package scala.actors
  * for all channels to which values can be sent.
  *
  * @author Philipp Haller
+ *
+ * @define actor `OutputChannel`
  */
 trait OutputChannel[-Msg] extends AbstractReactor[Msg] {
 
   /**
-   * Sends <code>msg</code> to this
-   * <code>OutputChannel</code> (asynchronous).
+   * Sends <code>msg</code> to this $actor (asynchronous).
    */
   def !(msg: Msg): Unit
 
   /**
-   * Sends <code>msg</code> to this
-   * <code>OutputChannel</code> (asynchronous) supplying
+   * Sends <code>msg</code> to this $actor (asynchronous) supplying
    * explicit reply destination.
    *
    * @param  msg      the message to send
@@ -35,14 +35,12 @@ trait OutputChannel[-Msg] extends AbstractReactor[Msg] {
   def send(msg: Msg, replyTo: OutputChannel[Any]): Unit
 
   /**
-   * Forwards <code>msg</code> to this
-   * <code>OutputChannel</code> (asynchronous).
+   * Forwards <code>msg</code> to this $actor (asynchronous).
    */
   def forward(msg: Msg): Unit
 
   /**
-   * Returns the <code>Actor</code> that is
-   * receiving from this <code>OutputChannel</code>.
+   * Returns the <code>Actor</code> that is receiving from this $actor.
    */
   def receiver: Actor
 }
diff --git a/src/actors/scala/actors/Reactor.scala b/src/actors/scala/actors/Reactor.scala
index db43921056..645b9bc2d3 100644
--- a/src/actors/scala/actors/Reactor.scala
+++ b/src/actors/scala/actors/Reactor.scala
@@ -50,23 +50,25 @@ private[actors] object Reactor {
  * The Reactor trait provides lightweight actors.
  *
  * @author Philipp Haller
+ *
+ * @define actor reactor
  */
 trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
 
-  /* The actor's mailbox. */
+  /* The $actor's mailbox. */
   private[actors] val mailbox = new MQueue[Msg]("Reactor")
 
   // guarded by this
   private[actors] val sendBuffer = new MQueue[Msg]("SendBuffer")
 
-  /* Whenever this actor executes on some thread, `waitingFor` is
+  /* Whenever this $actor executes on some thread, `waitingFor` is
    * guaranteed to be equal to `Reactor.waitingForNone`.
    *
    * In other words, whenever `waitingFor` is not equal to
-   * `Reactor.waitingForNone`, this actor is guaranteed not to execute
+   * `Reactor.waitingForNone`, this $actor is guaranteed not to execute
    * on some thread.
    *
-   * If the actor waits in a `react`, `waitingFor` holds the
+   * If the $actor waits in a `react`, `waitingFor` holds the
    * message handler that `react` was called with.
    *
    * guarded by this
@@ -78,8 +80,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
   private[actors] var _state: Actor.State.Value = Actor.State.New
 
   /**
-   * The behavior of a <code>Reactor</code> is specified by implementing
-   * this method.
+   * The $actor's behavior is specified by implementing this method.
    */
   def act(): Unit
 
@@ -92,13 +93,6 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
   protected[actors] def mailboxSize: Int =
     mailbox.size
 
-  /**
-   * Sends <code>msg</code> to this actor (asynchronous) supplying
-   * explicit reply destination.
-   *
-   * @param  msg      the message to send
-   * @param  replyTo  the reply destination
-   */
   def send(msg: Msg, replyTo: OutputChannel[Any]) {
     val todo = synchronized {
       if (waitingFor ne Reactor.waitingForNone) {
@@ -194,7 +188,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
   }
 
   /**
-   * Receives a message from this actor's mailbox.
+   * Receives a message from this $actor's mailbox.
    * <p>
    * This method never returns. Therefore, the rest of the computation
    * has to be contained in the actions of the partial function.
@@ -208,7 +202,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
   }
 
   /* This method is guaranteed to be executed from inside
-   * an actors act method.
+   * an $actor's act method.
    *
    * assume handler != null
    *
@@ -218,6 +212,9 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
     scheduler executeFromActor makeReaction(null, handler, msg)
   }
 
+  /**
+   * Starts this $actor.
+   */
   def start(): Reactor[Msg] = synchronized {
     if (_state == Actor.State.New) {
       _state = Actor.State.Runnable
@@ -228,7 +225,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
       this
   }
 
-  /** Returns the execution state of this actor.
+  /** Returns the execution state of this $actor.
    *
    *  @return the execution state
    */