Applying davetron5000's actors docs patches.

Review by phaller.

20 files changed, 109 insertions, 88 deletions

diff --git a/src/actors/scala/actors/AbstractActor.scala b/src/actors/scala/actors/AbstractActor.scala
index 63313ee1f6..3817f9cda3 100644
--- a/src/actors/scala/actors/AbstractActor.scala
+++ b/src/actors/scala/actors/AbstractActor.scala
@@ -10,8 +10,6 @@
 package scala.actors
 
 /**
- * The <code>AbstractActor</code> trait.
- *
  * @author Philipp Haller
  *
  * @define actor actor
diff --git a/src/actors/scala/actors/Actor.scala b/src/actors/scala/actors/Actor.scala
index 3f83a73256..98f5d2287f 100644
--- a/src/actors/scala/actors/Actor.scala
+++ b/src/actors/scala/actors/Actor.scala
@@ -13,7 +13,7 @@ import scala.util.control.ControlThrowable
 import java.util.{Timer, TimerTask}
 
 /**
- * The <code>Actor</code> object provides functions for the definition of
+ * Provides functions for the definition of
  * actors, as well as actor operations, such as
  * <code>receive</code>, <code>react</code>, <code>reply</code>,
  * etc.
@@ -22,22 +22,22 @@ import java.util.{Timer, TimerTask}
  */
 object Actor extends Combinators {
 
-  /** An actor state. An actor can be in one of the following states:
+  /** State of an actor.
    *  <ul>
-   *    <li>New<br>
-   *      An actor that has not yet started is in this state.</li>
-   *    <li>Runnable<br>
-   *      An actor executing is in this state.</li>
-   *    <li>Suspended<br>
-   *      An actor that is suspended waiting in a react is in this state.</li>
-   *    <li>TimedSuspended<br>
-   *      An actor that is suspended waiting in a reactWithin is in this state.</li>
-   *    <li>Blocked<br>
-   *      An actor that is blocked waiting in a receive is in this state.</li>
-   *    <li>TimedBlocked<br>
-   *      An actor that is blocked waiting in a receiveWithin is in this state.</li>
-   *    <li>Terminated<br>
-   *      An actor that has terminated is in this state.</li>
+   *    <li><b>New</b> -
+   *      Not yet started</li>
+   *    <li><b>Runnable</b> -
+   *      Executing</li>
+   *    <li><b>Suspended</b> -
+   *      Suspended, waiting in a `react`</li>
+   *    <li><b>TimedSuspended</b> -
+   *      Suspended, waiting in a `reactWithin` </li>
+   *    <li><b>Blocked</b> -
+   *      Blocked waiting in a `receive` </li>
+   *    <li><b>TimedBlocked</b> -
+   *      Blocked waiting in a `receiveWithin` </li>
+   *    <li><b>Terminated</b> -
+   *      Actor has terminated </li>
    *  </ul>
    */
   object State extends Enumeration {
@@ -115,11 +115,9 @@ object Actor extends Combinators {
   }
 
   /**
-   * This is a factory method for creating actors.
+   * Factory method for creating and starting an actor.
    *
-   * The following example demonstrates its usage:
-   *
-   * {{{
+   * @example {{{
    * import scala.actors.Actor._
    * ...
    * val a = actor {
@@ -140,12 +138,10 @@ object Actor extends Combinators {
   }
 
   /**
-   * This is a factory method for creating actors whose
+   * Factory method for creating actors whose
    * body is defined using a `Responder`.
    *
-   * The following example demonstrates its usage:
-   *
-   * {{{
+   * @example {{{
    * import scala.actors.Actor._
    * import Responder.exec
    * ...
@@ -182,6 +178,14 @@ object Actor extends Combinators {
    * <code>self</code>. Blocks if no message matching any of the
    * cases of <code>f</code> can be received.
    *
+   * @example {{{
+   * receive {
+   *   case "exit" => println("exiting")
+   *   case 42 => println("got the answer")
+   *   case x:Int => println("got an answer")
+   * }
+   * }}}
+   *
    * @param  f a partial function specifying patterns and actions
    * @return   the result of processing the received message
    */
@@ -210,6 +214,26 @@ object Actor extends Combinators {
    * computation of <code>self</code>, as this method will never
    * return.
    *
+   * A common method of continuting the computation is to send a message
+   * to another actor:
+   * {{{
+   * react {
+   *   case Get(from) =>
+   *     react {
+   *       case Put(x) => from ! x
+   *     }
+   * }
+   * }}}
+   *
+   * Another common method is to use `loop` to continuously `react` to messages:
+   * {{{
+   * loop {
+   *   react {
+   *     case Msg(data) => // process data
+   *   }
+   * }
+   * }}}
+   *
    * @param  f a partial function specifying patterns and actions
    * @return   this function never returns
    */
@@ -250,14 +274,14 @@ object Actor extends Combinators {
     rawSelf.sender
 
   /**
-   * Send <code>msg</code> to the actor waiting in a call to
+   * Sends <code>msg</code> to the actor waiting in a call to
    * <code>!?</code>.
    */
   def reply(msg: Any): Unit =
     rawSelf.reply(msg)
 
   /**
-   * Send <code>()</code> to the actor waiting in a call to
+   * Sends <code>()</code> to the actor waiting in a call to
    * <code>!?</code>.
    */
   def reply(): Unit =
@@ -274,9 +298,7 @@ object Actor extends Combinators {
    * Converts a synchronous event-based operation into
    * an asynchronous `Responder`.
    *
-   * The following example demonstrates its usage:
-   *
-   * {{{
+   * @example {{{
    * val adder = reactor {
    *   for {
    *     _ <- respondOn(react) { case Add(a, b) => reply(a+b) }
@@ -357,7 +379,7 @@ object Actor extends Combinators {
 
 /**
  * <p>
- *   This trait provides lightweight, concurrent actors. Actors are
+ *   Provides lightweight, concurrent actors. Actors are
  *   created by extending the `Actor` trait (alternatively, one of the
  *   factory methods in its companion object can be used).  The
  *   behavior of an `Actor` subclass is defined by implementing its
@@ -400,13 +422,13 @@ object Actor extends Combinators {
  *   <li>
  *     <a href="http://lampwww.epfl.ch/~odersky/papers/jmlc06.pdf">
  *     <span style="font-weight:bold; white-space:nowrap;">Event-Based
- *     Programming without Inversion of Control</span></a>,<br/>
+ *     Programming without Inversion of Control</span></a>,
  *     Philipp Haller and Martin Odersky, <i>Proc. JMLC 2006</i>, and
  *   </li>
  *   <li>
  *     <a href="http://lamp.epfl.ch/~phaller/doc/haller07coord.pdf">
  *     <span style="font-weight:bold; white-space:nowrap;">Actors that
- *     Unify Threads and Events</span></a>,<br/>
+ *     Unify Threads and Events</span></a>,
  *     Philipp Haller and Martin Odersky, <i>Proc. COORDINATION 2007</i>.
  *   </li>
  * </ul>
@@ -484,6 +506,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu
   private[actors] override def makeReaction(fun: () => Unit, handler: PartialFunction[Any, Any], msg: Any): Runnable =
     new ActorTask(this, fun, handler, msg)
 
+  /** See the companion object's `receive` method. */
   def receive[R](f: PartialFunction[Any, R]): R = {
     assert(Actor.self(scheduler) == this, "receive from channel belonging to other actor")
 
@@ -527,6 +550,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu
     result
   }
 
+  /** See the companion object's `receiveWithin` method. */
   def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R = {
     assert(Actor.self(scheduler) == this, "receive from channel belonging to other actor")
 
@@ -599,6 +623,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu
     result
   }
 
+  /** See the companion object's `react` method. */
   override def react(handler: PartialFunction[Any, Unit]): Nothing = {
     synchronized {
       if (shouldExit) exit()
@@ -606,6 +631,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu
     super.react(handler)
   }
 
+  /** See the companion object's `reactWithin` method. */
   override def reactWithin(msec: Long)(handler: PartialFunction[Any, Unit]): Nothing = {
     synchronized {
       if (shouldExit) exit()
@@ -613,6 +639,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu
     super.reactWithin(msec)(handler)
   }
 
+  /** Receives the next message from the mailbox */
   def ? : Any = receive {
     case x => x
   }
@@ -677,6 +704,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu
     this
   }
 
+  /** State of this actor */
   override def getState: Actor.State.Value = synchronized {
     if (isSuspended) {
       if (onTimeout.isEmpty)
@@ -850,27 +878,26 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu
 }
 
 
-/** <p>
- *    This object is used as the timeout pattern in
+/**
+ *    Used as the timeout pattern in
  *    <a href="Actor.html#receiveWithin(Long)" target="contentFrame">
  *    <code>receiveWithin</code></a> and
  *    <a href="Actor.html#reactWithin(Long)" target="contentFrame">
  *    <code>reactWithin</code></a>.
- *  </p>
- *  <p>
- *    The following example demonstrates its usage:
- *  </p><pre>
+ *
+ * @example {{{
  *    receiveWithin(500) {
- *      <b>case</b> (x, y) <b>=&gt;</b> ...
- *      <b>case</b> TIMEOUT <b>=&gt;</b> ...
- *    }</pre>
+ *      case (x, y) => ...
+ *      case TIMEOUT => ...
+ *    }
+ * }}}
  *
  *  @author Philipp Haller
  */
 case object TIMEOUT
 
 
-/** An `Exit` message (an instance of this class) is sent to an actor
+/** Sent to an actor
  *  with `trapExit` set to `true` whenever one of its linked actors
  *  terminates.
  *
@@ -879,10 +906,7 @@ case object TIMEOUT
  */
 case class Exit(from: AbstractActor, reason: AnyRef)
 
-/** <p>
- *    This class is used to manage control flow of actor
- *    executions.
- *  </p>
+/** Manages control flow of actor executions.
  *
  * @author Philipp Haller
  */
diff --git a/src/actors/scala/actors/ActorCanReply.scala b/src/actors/scala/actors/ActorCanReply.scala
index da53f482fd..b307aafa57 100644
--- a/src/actors/scala/actors/ActorCanReply.scala
+++ b/src/actors/scala/actors/ActorCanReply.scala
@@ -12,7 +12,7 @@ package scala.actors
 import scala.concurrent.SyncVar
 
 /**
- * The `ActorCanReply` trait provides message send operations that
+ * Provides message send operations that
  * may result in a response from the receiver.
  *
  * @author Philipp Haller
diff --git a/src/actors/scala/actors/ActorProxy.scala b/src/actors/scala/actors/ActorProxy.scala
index 7c9c5eab73..d4381ab706 100644
--- a/src/actors/scala/actors/ActorProxy.scala
+++ b/src/actors/scala/actors/ActorProxy.scala
@@ -12,7 +12,7 @@ package scala.actors
 import java.lang.Thread
 
 /**
- * The class <code>ActorProxy</code> provides a dynamic actor proxy for normal
+ * Provides a dynamic actor proxy for normal
  * Java threads.
  *
  * @author Philipp Haller
diff --git a/src/actors/scala/actors/ActorTask.scala b/src/actors/scala/actors/ActorTask.scala
index 3c7ef4c2dc..8d0379c095 100644
--- a/src/actors/scala/actors/ActorTask.scala
+++ b/src/actors/scala/actors/ActorTask.scala
@@ -10,10 +10,7 @@
 
 package scala.actors
 
-/** <p>
- *    The class <code>ActorTask</code>.
- *  </p>
- *
+/**
  *  @author Philipp Haller
  */
 private[actors] class ActorTask(actor: Actor,
diff --git a/src/actors/scala/actors/CanReply.scala b/src/actors/scala/actors/CanReply.scala
index 6d8667be28..a4619a986e 100644
--- a/src/actors/scala/actors/CanReply.scala
+++ b/src/actors/scala/actors/CanReply.scala
@@ -12,7 +12,7 @@ package scala.actors
 import scala.annotation.unique.unique
 
 /**
- * The <code>CanReply</code> trait defines result-bearing message send operations.
+ * Defines result-bearing message send operations.
  *
  * @author Philipp Haller
  *
diff --git a/src/actors/scala/actors/Channel.scala b/src/actors/scala/actors/Channel.scala
index 44ec25b7b3..f4898775fc 100644
--- a/src/actors/scala/actors/Channel.scala
+++ b/src/actors/scala/actors/Channel.scala
@@ -12,15 +12,14 @@ package scala.actors
 import scala.concurrent.SyncVar
 
 /**
- *  This class is used to pattern match on values that were sent
+ *  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>.
  *
- *  The following example demonstrates its usage:
- *  {{{
+ *  @example {{{
  *  receive {
- *    <b>case</b> Chan1 ! msg1 => ...
- *    <b>case</b> Chan2 ! msg2 => ...
+ *    case Chan1 ! msg1 => ...
+ *    case Chan2 ! msg2 => ...
  *  }
  *  }}}
  *
@@ -29,7 +28,7 @@ import scala.concurrent.SyncVar
 case class ! [a](ch: Channel[a], msg: a)
 
 /**
- * This class provides a means for typed communication among
+ * Provides a means for typed communication among
  * actors. Only the actor creating an instance of a
  * <code>Channel</code> may receive from it.
  *
diff --git a/src/actors/scala/actors/Future.scala b/src/actors/scala/actors/Future.scala
index 7991b9b288..20e2de47a5 100644
--- a/src/actors/scala/actors/Future.scala
+++ b/src/actors/scala/actors/Future.scala
@@ -12,9 +12,8 @@ package scala.actors
 import scala.actors.scheduler.DaemonScheduler
 import scala.concurrent.SyncVar
 
-/** A `Future[T]` is a function of arity 0 that returns
- *  a value of type `T`.
- *  Applying a future blocks the current actor (`Actor.self`)
+/** A function of arity 0, returing a value of type `T` that,
+ *  when applied, blocks the current actor (`Actor.self`)
  *  until the future's value is available.
  *
  *  A future can be queried to find out whether its value
@@ -110,7 +109,7 @@ private class FutureActor[T](fun: SyncVar[T] => Unit, channel: Channel[T]) exten
   }
 }
 
-/** The `Futures` object contains methods that operate on futures.
+/** Methods that operate on futures.
  *
  *  @author Philipp Haller
  */
diff --git a/src/actors/scala/actors/IScheduler.scala b/src/actors/scala/actors/IScheduler.scala
index 5f91448bb8..5e0b6c0d0c 100644
--- a/src/actors/scala/actors/IScheduler.scala
+++ b/src/actors/scala/actors/IScheduler.scala
@@ -10,7 +10,7 @@
 package scala.actors
 
 /**
- * The <code>IScheduler</code> trait provides a common interface
+ * A common interface
  * for all schedulers used to execute actor tasks.
  *
  * Subclasses of <code>Actor</code> that override its
diff --git a/src/actors/scala/actors/InputChannel.scala b/src/actors/scala/actors/InputChannel.scala
index d5eac40f71..51e739b0fb 100644
--- a/src/actors/scala/actors/InputChannel.scala
+++ b/src/actors/scala/actors/InputChannel.scala
@@ -10,8 +10,7 @@
 package scala.actors
 
 /**
- * The <code>InputChannel</code> trait provides a common interface
- * for all channels from which values can be received.
+ * A common interface for all channels from which values can be received.
  *
  * @author Philipp Haller
  *
diff --git a/src/actors/scala/actors/OutputChannel.scala b/src/actors/scala/actors/OutputChannel.scala
index 70de12f12f..d68e49a1b1 100644
--- a/src/actors/scala/actors/OutputChannel.scala
+++ b/src/actors/scala/actors/OutputChannel.scala
@@ -12,8 +12,7 @@ package scala.actors
 import scala.annotation.unique.unique
 
 /**
- * The <code>OutputChannel</code> trait provides a common interface
- * for all channels to which values can be sent.
+ * A common interface for all channels to which values can be sent.
  *
  * @author Philipp Haller
  *
diff --git a/src/actors/scala/actors/ReactChannel.scala b/src/actors/scala/actors/ReactChannel.scala
index f338ccfcd3..9b6c1c5c77 100644
--- a/src/actors/scala/actors/ReactChannel.scala
+++ b/src/actors/scala/actors/ReactChannel.scala
@@ -10,8 +10,6 @@
 package scala.actors
 
 /**
- * The <code>ReactChannel</code> trait.
- *
  * @author Philipp Haller
  */
 private[actors] class ReactChannel[Msg](receiver: ReplyReactor) extends InputChannel[Msg] {
diff --git a/src/actors/scala/actors/Reactor.scala b/src/actors/scala/actors/Reactor.scala
index 3853d7d787..507c18d04e 100644
--- a/src/actors/scala/actors/Reactor.scala
+++ b/src/actors/scala/actors/Reactor.scala
@@ -46,7 +46,7 @@ private[actors] object Reactor {
 }
 
 /**
- * The Reactor trait provides lightweight actors.
+ * Super trait of all actor traits.
  *
  * @author Philipp Haller
  *
diff --git a/src/actors/scala/actors/ReactorCanReply.scala b/src/actors/scala/actors/ReactorCanReply.scala
index f6df4ed02f..68f9999776 100644
--- a/src/actors/scala/actors/ReactorCanReply.scala
+++ b/src/actors/scala/actors/ReactorCanReply.scala
@@ -10,7 +10,7 @@
 package scala.actors
 
 /**
- * The ReactorCanReply trait provides message send operations that
+ * Provides message send operations that
  * may result in a response from the receiver.
  *
  * @author Philipp Haller
diff --git a/src/actors/scala/actors/ReactorTask.scala b/src/actors/scala/actors/ReactorTask.scala
index 6d87f880d7..98099c4320 100644
--- a/src/actors/scala/actors/ReactorTask.scala
+++ b/src/actors/scala/actors/ReactorTask.scala
@@ -14,10 +14,7 @@ import java.util.concurrent.Callable
 
 import scala.concurrent.forkjoin.RecursiveAction
 
-/** <p>
- *    The class <code>ReactorTask</code>.
- *  </p>
- *
+/**
  *  @author Philipp Haller
  */
 private[actors] class ReactorTask[Msg >: Null](var reactor: Reactor[Msg],
diff --git a/src/actors/scala/actors/ReplyReactor.scala b/src/actors/scala/actors/ReplyReactor.scala
index 2e567bf697..85ef0d38d3 100644
--- a/src/actors/scala/actors/ReplyReactor.scala
+++ b/src/actors/scala/actors/ReplyReactor.scala
@@ -11,12 +11,11 @@ package scala.actors
 
 import java.util.{Timer, TimerTask}
 
-/** <p>
- *    The <code>ReplyReactor</code> trait extends the <code>Reactor</code>
+/**
+ * Extends the [[scala.actors.Reactor]]
  *    trait with methods to reply to the sender of a message.
  *    Sending a message to a <code>ReplyReactor</code> implicitly
  *    passes a reference to the sender together with the message.
- *  </p>
  *
  *  @author Philipp Haller
  *
diff --git a/src/actors/scala/actors/ReplyReactorTask.scala b/src/actors/scala/actors/ReplyReactorTask.scala
index 9e3e7c0700..1db722f89b 100644
--- a/src/actors/scala/actors/ReplyReactorTask.scala
+++ b/src/actors/scala/actors/ReplyReactorTask.scala
@@ -10,10 +10,7 @@
 
 package scala.actors
 
-/** <p>
- *    The class <code>ReplyReactorTask</code>.
- *  </p>
- *
+/**
  *  @author Philipp Haller
  */
 private[actors] class ReplyReactorTask(reactor: ReplyReactor,
diff --git a/src/actors/scala/actors/Scheduler.scala b/src/actors/scala/actors/Scheduler.scala
index 112221a469..8d0cac44ea 100644
--- a/src/actors/scala/actors/Scheduler.scala
+++ b/src/actors/scala/actors/Scheduler.scala
@@ -13,7 +13,7 @@ import java.util.concurrent._
 import scheduler.{DelegatingScheduler, ForkJoinScheduler, ResizableThreadPoolScheduler, ThreadPoolConfig}
 
 /**
- * The <code>Scheduler</code> object is used by <code>Actor</code> to
+ * Used by [[scala.actors.Actor]] instances to
  * execute tasks of an actor execution.
  *
  * @author Philipp Haller
diff --git a/src/actors/scala/actors/SchedulerAdapter.scala b/src/actors/scala/actors/SchedulerAdapter.scala
index ebfd5fe42f..110f3582c9 100644
--- a/src/actors/scala/actors/SchedulerAdapter.scala
+++ b/src/actors/scala/actors/SchedulerAdapter.scala
@@ -9,8 +9,8 @@
 
 package scala.actors
 
-/** The <code>SchedulerAdapter</code> trait is used to adapt
- *  the behavior of the standard <code>Scheduler</code> object.
+/** Adapts
+ *  the behavior of the standard [[scala.actors.Scheduler]] object.
  *
  *  Providing an implementation for the
  *  <code>execute(f: => Unit)</code> method is sufficient to
diff --git a/src/actors/scala/actors/package.scala b/src/actors/scala/actors/package.scala
index 66ba05b1dd..55bc8e113f 100644
--- a/src/actors/scala/actors/package.scala
+++ b/src/actors/scala/actors/package.scala
@@ -1,5 +1,20 @@
 package scala
 
+/**
+ * A library that provides both asynchronous and synchronous messaging to allow
+ * for concurrent programming without explicit synchronization.
+ *
+ * == Guide ==
+ *
+ * A detailed guide for the actors library is available
+ * [[http://www.scala-lang.org/docu/files/actors-api/actors_api_guide.html#]].
+ *
+ * == Getting Started ==
+ *
+ * A starting point for using the actors library would be [[scala.actors.Reactor]],
+ * [[scala.actors.ReplyReactor]], or [[scala.actors.Actor]] or their companion objects.
+ *
+ */
 package object actors {
 
   // type of Reactors tracked by termination detector