Scaladoc clean-ups for various actor and channe...

Scaladoc clean-ups for various actor and channel types. Actor now
extends InputChannel. Channel now extends CanReply. Review by plocinic.

9 files changed, 30 insertions, 162 deletions

diff --git a/src/actors/scala/actors/AbstractActor.scala b/src/actors/scala/actors/AbstractActor.scala
index 9cc62a1cde..80b1e76b30 100644
--- a/src/actors/scala/actors/AbstractActor.scala
+++ b/src/actors/scala/actors/AbstractActor.scala
@@ -14,6 +14,8 @@ package scala.actors
  * The <code>AbstractActor</code> trait.
  *
  * @author Philipp Haller
+ *
+ * @define actor actor
  */
 trait AbstractActor extends OutputChannel[Any] with CanReply[Any, Any] {
 
diff --git a/src/actors/scala/actors/Actor.scala b/src/actors/scala/actors/Actor.scala
index c2c967fe69..ccd60f666c 100644
--- a/src/actors/scala/actors/Actor.scala
+++ b/src/actors/scala/actors/Actor.scala
@@ -384,9 +384,10 @@ object Actor extends Combinators {
  * @author Philipp Haller
  *
  * @define actor actor
+ * @define channel actor's mailbox
  */
 @serializable @SerialVersionUID(-781154067877019505L)
-trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
+trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with InputChannel[Any] {
 
   /* The following two fields are only used when the actor
    * suspends by blocking its underlying thread, for example,
@@ -415,12 +416,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
   private[actors] override def makeReaction(fun: () => Unit, handler: PartialFunction[Any, Any], msg: Any): Runnable =
     new ActorTask(this, fun, handler, msg)
 
-  /**
-   * Receives a message from this actor's mailbox.
-   *
-   * @param  f    a partial function with message patterns and actions
-   * @return      result of processing the received value
-   */
   def receive[R](f: PartialFunction[Any, R]): R = {
     assert(Actor.self(scheduler) == this, "receive from channel belonging to other actor")
 
@@ -464,14 +459,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
     result
   }
 
-  /**
-   * Receives a message from this actor's mailbox within a certain
-   * time span.
-   *
-   * @param  msec the time span before timeout
-   * @param  f    a partial function with message patterns and actions
-   * @return      result of processing the received value
-   */
   def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R = {
     assert(Actor.self(scheduler) == this, "receive from channel belonging to other actor")
 
@@ -558,9 +545,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
     super.reactWithin(msec)(handler)
   }
 
-  /**
-   * Receives the next message from this actor's mailbox.
-   */
   def ? : Any = receive {
     case x => x
   }
diff --git a/src/actors/scala/actors/ActorCanReply.scala b/src/actors/scala/actors/ActorCanReply.scala
index 8cba425b4c..fdc3833ec4 100644
--- a/src/actors/scala/actors/ActorCanReply.scala
+++ b/src/actors/scala/actors/ActorCanReply.scala
@@ -13,7 +13,7 @@ package scala.actors
 import java.util.concurrent.ExecutionException
 
 /**
- * The ActorCanReply trait provides message send operations that
+ * The `ActorCanReply` trait provides message send operations that
  * may result in a response from the receiver.
  *
  * @author Philipp Haller
@@ -21,13 +21,6 @@ import java.util.concurrent.ExecutionException
 private[actors] trait ActorCanReply extends ReactorCanReply {
   thiz: AbstractActor with ReplyReactor =>
 
-  /**
-   * Sends <code>msg</code> to this actor and awaits reply
-   * (synchronous).
-   *
-   * @param  msg the message to be sent
-   * @return     the reply
-   */
   override def !?(msg: Any): Any = {
     val replyCh = new Channel[Any](Actor.self(thiz.scheduler))
     thiz.send(msg, replyCh)
@@ -36,15 +29,6 @@ private[actors] trait ActorCanReply extends ReactorCanReply {
     }
   }
 
-  /**
-   * Sends <code>msg</code> to this actor and awaits reply
-   * (synchronous) within <code>msec</code> milliseconds.
-   *
-   * @param  msec the time span before timeout
-   * @param  msg  the message to be sent
-   * @return      <code>None</code> in case of timeout, otherwise
-   *              <code>Some(x)</code> where <code>x</code> is the reply
-   */
   override def !?(msec: Long, msg: Any): Option[Any] = {
     val replyCh = new Channel[Any](Actor.self(thiz.scheduler))
     thiz.send(msg, replyCh)
@@ -54,13 +38,6 @@ private[actors] trait ActorCanReply extends ReactorCanReply {
     }
   }
 
-  /**
-   * Sends <code>msg</code> to this actor and immediately
-   * returns a future representing the reply value.
-   * The reply is post-processed using the partial function
-   * <code>handler</code>. This also allows to recover a more
-   * precise type for the reply value.
-   */
   override def !![A](msg: Any, handler: PartialFunction[Any, A]): Future[A] = {
     val ftch = new Channel[A](Actor.self(thiz.scheduler))
     thiz.send(msg, new OutputChannel[Any] {
@@ -76,10 +53,6 @@ private[actors] trait ActorCanReply extends ReactorCanReply {
     Futures.fromInputChannel(ftch)
   }
 
-  /**
-   * Sends <code>msg</code> to this actor and immediately
-   * returns a future representing the reply value.
-   */
   override def !!(msg: Any): Future[Any] = {
     val ftch = new Channel[Any](Actor.self(thiz.scheduler))
     val linkedChannel = new AbstractActor {
diff --git a/src/actors/scala/actors/CanReply.scala b/src/actors/scala/actors/CanReply.scala
index 23f0a5319b..99e1169900 100644
--- a/src/actors/scala/actors/CanReply.scala
+++ b/src/actors/scala/actors/CanReply.scala
@@ -14,11 +14,13 @@ package scala.actors
  * The <code>CanReply</code> trait defines result-bearing message send operations.
  *
  * @author Philipp Haller
+ *
+ * @define actor `CanReply`
  */
 trait CanReply[-T, +R] {
 
   /**
-   * Sends <code>msg</code> to this <code>CanReply</code> and
+   * Sends <code>msg</code> to this $actor and
    * awaits reply (synchronous).
    *
    * @param  msg the message to be sent
@@ -27,7 +29,7 @@ trait CanReply[-T, +R] {
   def !?(msg: T): R
 
   /**
-   * Sends <code>msg</code> to this <code>CanReply</code> and
+   * Sends <code>msg</code> to this $actor and
    * awaits reply (synchronous) within <code>msec</code>
    * milliseconds.
    *
@@ -39,7 +41,7 @@ trait CanReply[-T, +R] {
   def !?(msec: Long, msg: T): Option[R]
 
   /**
-   * Sends <code>msg</code> to this <code>CanReply</code> and
+   * Sends <code>msg</code> to this $actor and
    * immediately returns a future representing the reply value.
    *
    * @param  msg the message to be sent
@@ -49,7 +51,7 @@ trait CanReply[-T, +R] {
     () => this !? msg
 
   /**
-   * Sends <code>msg</code> to this <code>CanReply</code> and
+   * Sends <code>msg</code> to this $actor and
    * immediately returns a future representing the reply value.
    * The reply is post-processed using the partial function
    * <code>handler</code>. This also allows to recover a more
diff --git a/src/actors/scala/actors/Channel.scala b/src/actors/scala/actors/Channel.scala
index 4c37de7665..e40a804e4a 100644
--- a/src/actors/scala/actors/Channel.scala
+++ b/src/actors/scala/actors/Channel.scala
@@ -35,45 +35,26 @@ case class ! [a](ch: Channel[a], msg: a)
  * <code>Channel</code> may receive from it.
  *
  * @author Philipp Haller
+ *
+ * @define actor channel
+ * @define channel channel
  */
-class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputChannel[Msg] {
+class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputChannel[Msg] with CanReply[Msg, Any] {
 
   def this() = this(Actor.self)
 
-  /**
-   * Sends a message to this <code>Channel</code>.
-   *
-   * @param  msg the message to be sent
-   */
   def !(msg: Msg) {
     receiver ! scala.actors.!(this, msg)
   }
 
-  /**
-   * Sends a message to this <code>Channel</code>
-   * (asynchronous) supplying explicit reply destination.
-   *
-   * @param  msg     the message to send
-   * @param  replyTo the reply destination
-   */
   def send(msg: Msg, replyTo: OutputChannel[Any]) {
     receiver.send(scala.actors.!(this, msg), replyTo)
   }
 
-  /**
-   * Forwards <code>msg</code> to <code>this</code> keeping the
-   * last sender as sender instead of <code>self</code>.
-   */
   def forward(msg: Msg) {
     receiver forward scala.actors.!(this, msg)
   }
 
-  /**
-   * Receives a message from this <code>Channel</code>.
-   *
-   * @param  f    a partial function with message patterns and actions
-   * @return      result of processing the received value
-   */
   def receive[R](f: PartialFunction[Msg, R]): R = {
     val C = this.asInstanceOf[Channel[Any]]
     val recvActor = receiver.asInstanceOf[Actor]
@@ -82,21 +63,10 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha
     }
   }
 
-  /**
-   * Receives the next message from this <code>Channel</code>.
-   */
   def ? : Msg = receive {
     case x => x
   }
 
-  /**
-   * Receives a message from this <code>Channel</code> within a certain
-   * time span.
-   *
-   * @param  msec the time span before timeout
-   * @param  f    a partial function with message patterns and actions
-   * @return      result of processing the received value
-   */
   def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R = {
     val C = this.asInstanceOf[Channel[Any]]
     val recvActor = receiver.asInstanceOf[Actor]
@@ -106,14 +76,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha
     }
   }
 
-  /**
-   * Receives a message from this <code>Channel</code>.
-   * <p>
-   * This method never returns. Therefore, the rest of the computation
-   * has to be contained in the actions of the partial function.
-   *
-   * @param  f    a partial function with message patterns and actions
-   */
   def react(f: PartialFunction[Msg, Unit]): Nothing = {
     val C = this.asInstanceOf[Channel[Any]]
     receiver.react {
@@ -121,16 +83,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha
     }
   }
 
-  /**
-   * Receives a message from this <code>Channel</code> within a certain
-   * time span.
-   * <p>
-   * This method never returns. Therefore, the rest of the computation
-   * has to be contained in the actions of the partial function.
-   *
-   * @param  msec the time span before timeout
-   * @param  f    a partial function with message patterns and actions
-   */
   def reactWithin(msec: Long)(f: PartialFunction[Any, Unit]): Nothing = {
     val C = this.asInstanceOf[Channel[Any]]
     val recvActor = receiver.asInstanceOf[Actor]
@@ -140,13 +92,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha
     }
   }
 
-  /**
-   * Sends a message to this <code>Channel</code> and
-   * awaits reply.
-   *
-   * @param  msg the message to be sent
-   * @return     the reply
-   */
   def !?(msg: Msg): Any = {
     val replyCh = new Channel[Any](Actor.self(receiver.scheduler))
     receiver.send(scala.actors.!(this, msg), replyCh)
@@ -155,15 +100,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha
     }
   }
 
-  /**
-   * Sends a message to this <code>Channel</code> and
-   * awaits reply within a certain time span.
-   *
-   * @param  msec the time span before timeout
-   * @param  msg  the message to be sent
-   * @return      <code>None</code> in case of timeout, otherwise
-   *              <code>Some(x)</code> where <code>x</code> is the reply
-   */
   def !?(msec: Long, msg: Msg): Option[Any] = {
     val replyCh = new Channel[Any](Actor.self(receiver.scheduler))
     receiver.send(scala.actors.!(this, msg), replyCh)
diff --git a/src/actors/scala/actors/InputChannel.scala b/src/actors/scala/actors/InputChannel.scala
index fa2fad43c6..dfe26b3462 100644
--- a/src/actors/scala/actors/InputChannel.scala
+++ b/src/actors/scala/actors/InputChannel.scala
@@ -15,11 +15,13 @@ package scala.actors
  * for all channels from which values can be received.
  *
  * @author Philipp Haller
+ *
+ * @define channel `InputChannel`
  */
 trait InputChannel[+Msg] {
 
   /**
-   * Receives a message from this <code>InputChannel</code>.
+   * Receives a message from this $channel.
    *
    * @param  f    a partial function with message patterns and actions
    * @return      result of processing the received value
@@ -27,7 +29,7 @@ trait InputChannel[+Msg] {
   def receive[R](f: PartialFunction[Msg, R]): R
 
   /**
-   * Receives a message from this <code>InputChannel</code> within
+   * Receives a message from this $channel within
    * a certain time span.
    *
    * @param  msec the time span before timeout
@@ -37,8 +39,8 @@ trait InputChannel[+Msg] {
   def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R
 
   /**
-   * Receives a message from this <code>InputChannel</code>.
-   * <p>
+   * Receives a message from this $channel.
+   *
    * This method never returns. Therefore, the rest of the computation
    * has to be contained in the actions of the partial function.
    *
@@ -47,9 +49,9 @@ trait InputChannel[+Msg] {
   def react(f: PartialFunction[Msg, Unit]): Nothing
 
   /**
-   * Receives a message from this <code>InputChannel</code> within
+   * Receives a message from this $channel within
    * a certain time span.
-   * <p>
+   *
    * This method never returns. Therefore, the rest of the computation
    * has to be contained in the actions of the partial function.
    *
@@ -59,7 +61,7 @@ trait InputChannel[+Msg] {
   def reactWithin(msec: Long)(f: PartialFunction[Any, Unit]): Nothing
 
   /**
-   * Receives the next message from this <code>Channel</code>.
+   * Receives the next message from this $channel.
    */
   def ? : Msg
 }
diff --git a/src/actors/scala/actors/Reactor.scala b/src/actors/scala/actors/Reactor.scala
index 645b9bc2d3..a5bdcf1dd9 100644
--- a/src/actors/scala/actors/Reactor.scala
+++ b/src/actors/scala/actors/Reactor.scala
@@ -189,7 +189,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
 
   /**
    * 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.
    *
diff --git a/src/actors/scala/actors/ReactorCanReply.scala b/src/actors/scala/actors/ReactorCanReply.scala
index c53e3a78e1..9002a55b87 100644
--- a/src/actors/scala/actors/ReactorCanReply.scala
+++ b/src/actors/scala/actors/ReactorCanReply.scala
@@ -19,25 +19,9 @@ package scala.actors
 private[actors] trait ReactorCanReply extends CanReply[Any, Any] {
   _: ReplyReactor =>
 
-  /**
-   * Sends <code>msg</code> to this actor and awaits reply
-   * (synchronous).
-   *
-   * @param  msg the message to be sent
-   * @return     the reply
-   */
   def !?(msg: Any): Any =
     (this !! msg)()
 
-  /**
-   * Sends <code>msg</code> to this actor and awaits reply
-   * (synchronous) within <code>msec</code> milliseconds.
-   *
-   * @param  msec the time span before timeout
-   * @param  msg  the message to be sent
-   * @return      <code>None</code> in case of timeout, otherwise
-   *              <code>Some(x)</code> where <code>x</code> is the reply
-   */
   def !?(msec: Long, msg: Any): Option[Any] = {
     val myself = Actor.rawSelf(this.scheduler)
     val res = new scala.concurrent.SyncVar[Any]
@@ -55,20 +39,9 @@ private[actors] trait ReactorCanReply extends CanReply[Any, Any] {
     res.get(msec)
   }
 
-  /**
-   * Sends <code>msg</code> to this actor and immediately
-   * returns a future representing the reply value.
-   */
   override def !!(msg: Any): Future[Any] =
     this !! (msg, { case x => x })
 
-  /**
-   * Sends <code>msg</code> to this actor and immediately
-   * returns a future representing the reply value.
-   * The reply is post-processed using the partial function
-   * <code>handler</code>. This also allows to recover a more
-   * precise type for the reply value.
-   */
   override def !![A](msg: Any, handler: PartialFunction[Any, A]): Future[A] = {
     val myself = Actor.rawSelf(this.scheduler)
     val ftch = new ReactChannel[A](myself)
diff --git a/src/actors/scala/actors/ReplyReactor.scala b/src/actors/scala/actors/ReplyReactor.scala
index 26057ab9cb..665ed3091f 100644
--- a/src/actors/scala/actors/ReplyReactor.scala
+++ b/src/actors/scala/actors/ReplyReactor.scala
@@ -20,6 +20,8 @@ import java.util.{Timer, TimerTask}
  *  </p>
  *
  *  @author Philipp Haller
+ *
+ *  @define actor `ReplyReactor`
  */
 trait ReplyReactor extends Reactor[Any] with ReactorCanReply {
 
@@ -38,7 +40,7 @@ trait ReplyReactor extends Reactor[Any] with ReactorCanReply {
   private[actors] var onTimeout: Option[TimerTask] = None
 
   /**
-   * Returns the actor which sent the last received message.
+   * Returns the $actor which sent the last received message.
    */
   protected[actors] def sender: OutputChannel[Any] = senders.head
 
@@ -49,16 +51,10 @@ trait ReplyReactor extends Reactor[Any] with ReactorCanReply {
     sender ! msg
   }
 
-  /**
-   * Sends <code>msg</code> to this actor (asynchronous).
-   */
   override def !(msg: Any) {
     send(msg, Actor.rawSelf(scheduler))
   }
 
-  /**
-   * Forwards <code>msg</code> to this actor (asynchronous).
-   */
   override def forward(msg: Any) {
     send(msg, Actor.sender)
   }
@@ -115,9 +111,9 @@ trait ReplyReactor extends Reactor[Any] with ReactorCanReply {
   }
 
   /**
-   * Receives a message from this actor's mailbox within a certain
+   * Receives a message from this $actor's mailbox within a certain
    * time span.
-   * <p>
+   *
    * This method never returns. Therefore, the rest of the computation
    * has to be contained in the actions of the partial function.
    *