improved Scala comments in scala/concurrent/*.s...

improved Scala comments in scala/concurrent/*.scala

6 files changed, 152 insertions, 89 deletions

diff --git a/src/library/scala/concurrent/SyncChannel.scala b/src/library/scala/concurrent/SyncChannel.scala
index d7ae5fb366..afbf067881 100644
--- a/src/library/scala/concurrent/SyncChannel.scala
+++ b/src/library/scala/concurrent/SyncChannel.scala
@@ -9,32 +9,36 @@
 // $Id$
 
 
-package scala.concurrent;
-
+package scala.concurrent
 
+/** The class <code>SyncChannel</code> ...
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 10/03/2003
+ */
 class SyncChannel[a] {
-  private var data: a = _;
-  private var reading = false;
-  private var writing = false;
+  private var data: a = _
+  private var reading = false
+  private var writing = false
 
-  def await(cond: => Boolean) = while (!cond) { wait() }
+  def await(cond: => Boolean) = while (!cond) wait()
 
   def write(x: a) = synchronized {
-    await(!writing);
-    data = x;
-    writing = true;
-    if (reading) notifyAll();
+    await(!writing)
+    data = x
+    writing = true
+    if (reading) notifyAll()
     else await(reading)
   }
 
   def read: a = synchronized {
-    await(!reading);
-    reading = true;
-    await(writing);
-    val x = data;
-    writing = false;
-    reading = false;
-    notifyAll();
+    await(!reading)
+    reading = true
+    await(writing)
+    val x = data
+    writing = false
+    reading = false
+    notifyAll()
     x
   }
 }
diff --git a/src/library/scala/concurrent/SyncVar.scala b/src/library/scala/concurrent/SyncVar.scala
index b0a76d73b4..796133fc00 100644
--- a/src/library/scala/concurrent/SyncVar.scala
+++ b/src/library/scala/concurrent/SyncVar.scala
@@ -9,27 +9,31 @@
 // $Id$
 
 
-package scala.concurrent;
+package scala.concurrent
 
 
+/** The class <code>SyncVar</code> ...
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 10/03/2003
+ */
 class SyncVar[a] {
-
-  private var isDefined: Boolean = false;
-  private var value: a = _;
+  private var isDefined: Boolean = false
+  private var value: a = _
 
   def get = synchronized {
-    if (!isDefined) wait();
+    if (!isDefined) wait()
     value
   }
 
   def set(x: a) = synchronized {
-    value = x;
-    isDefined = true;
+    value = x
+    isDefined = true
     notifyAll()
   }
 
   def isSet: Boolean = synchronized {
-    isDefined;
+    isDefined
   }
 
   def unset = synchronized {
diff --git a/src/library/scala/concurrent/jolib.scala b/src/library/scala/concurrent/jolib.scala
index 6388f9a495..7fb6eebb09 100644
--- a/src/library/scala/concurrent/jolib.scala
+++ b/src/library/scala/concurrent/jolib.scala
@@ -9,38 +9,41 @@
 // $Id$
 
 
-package scala.concurrent;
+package scala.concurrent
 
 
 /**
-* Library for using join-calculus concurrent primitives in Scala.
-*/
+ * Library for using join-calculus concurrent primitives in Scala.
+ *
+ * @author  Vincent Cremet
+ * @version 1.0, 17/10/2003
+ */
 object jolib {
 
-  type Pattern = List[Signal];
+  type Pattern = List[Signal]
 
-  type Rule = PartialFunction[List[Any], unit];
+  type Rule = PartialFunction[List[Any], unit]
 
   /////////////////// JOIN DEFINITION /////////////////////////
 
   class Join {
 
-    private var ruls: List[Pair[Pattern, Rule]] = null;
+    private var ruls: List[Pair[Pattern, Rule]] = null
 
     def canMatch(p: Pattern) =
-      p forall { s => !s.queue.isEmpty };
+      p forall { s => !s.queue.isEmpty }
 
     def values(p: Pattern): List[Any] =
-      p map { s => s.queue.dequeue: Any };
+      p map { s => s.queue.dequeue: Any }
 
     def rules(rs: Pair[Pattern, Rule]*) =
-      ruls = rs.asInstanceOf[List[Pair[Pattern, Rule]]];
+      ruls = rs.asInstanceOf[List[Pair[Pattern, Rule]]]
 
     def tryMatch =
       (ruls find { case Pair(p, _) => canMatch(p) }) match {
-        case None => () => ();
+        case None => () => ()
         case Some(Pair(p, r)) => {
-          val args = values(p);
+          val args = values(p)
           () => concurrent.ops.spawn(r(args))
         }
       }
@@ -50,25 +53,25 @@ object jolib {
   /////////////////// SIGNALS /////////////////////////
 
   abstract class Signal(join: Join) {
-    type C;
-    val queue = new collection.mutable.Queue[C];
+    type C
+    val queue = new collection.mutable.Queue[C]
     def tryReduction(x: C): unit = {
       val continuation = join synchronized {
-        queue.enqueue(x);
+        queue.enqueue(x)
         join.tryMatch
-      };
+      }
       continuation()
     }
   }
 
   abstract class Asynchr(join: Join) extends Signal(join) {
-    def apply(x: C): unit = tryReduction(x);
+    def apply(x: C): unit = tryReduction(x)
   }
 
   abstract class Synchr[a](join: Join) extends Signal(join) {
-    type C <: SyncVar[a];
+    type C <: SyncVar[a]
     def apply(x: C): a = {
-      tryReduction(x);
+      tryReduction(x)
       x.get
     }
   }
diff --git a/src/library/scala/concurrent/ops.scala b/src/library/scala/concurrent/ops.scala
index 584ac4e738..e70a0ed606 100644
--- a/src/library/scala/concurrent/ops.scala
+++ b/src/library/scala/concurrent/ops.scala
@@ -9,35 +9,57 @@
 // $Id$
 
 
-package scala.concurrent;
+package scala.concurrent
 
 
+/** The object <code>ops</code> ...
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 12/03/2003
+ */
 object ops {
 
+  /**
+   *  @param p ...
+   */
   def spawn(p: => Unit) = {
-    val t = new Thread() { override def run() = p; }
+    val t = new Thread() { override def run() = p }
     t.start()
   }
 
+  /**
+   *  @param p ...
+   *  @return  ...
+   */
   def future[a](p: => a): () => a = {
-    val result = new SyncVar[a];
+    val result = new SyncVar[a]
     spawn { result set p }
     () => result.get
   }
 
+  /**
+   *  @param xp ...
+   *  @param yp ...
+   *  @return   ...
+   */
   def par[a, b](xp: => a, yp: => b): Pair[a, b] = {
-    val y = new SyncVar[b];
+    val y = new SyncVar[b]
     spawn { y set yp }
     Pair(xp, y.get)
   }
 
+  /**
+   *  @param start ...
+   *  @param end   ...
+   *  @param p     ...
+   */
   def replicate(start: Int, end: Int)(p: Int => Unit): Unit = {
     if (start == end)
       ()
     else if (start + 1 == end)
       p(start)
     else {
-      val mid = (start + end) / 2;
+      val mid = (start + end) / 2
       spawn { replicate(start, mid)(p) }
       replicate(mid, end)(p)
     }
diff --git a/src/library/scala/concurrent/pilib.scala b/src/library/scala/concurrent/pilib.scala
index 19cc8f836e..506b0c2d2e 100644
--- a/src/library/scala/concurrent/pilib.scala
+++ b/src/library/scala/concurrent/pilib.scala
@@ -13,28 +13,30 @@ package scala.concurrent
 
 
 /**
-* Library for using Pi-calculus concurrent primitives in Scala. As an example,
-the definition of a two-place buffer using the <b>pilib</b> library looks like:
-*<pre>
-*def Buffer[a](put: Chan[a], get: Chan[a]): unit = {
-*  def B0: unit = choice ( put * { x => B1(x) } );
-*  def B1(x: a): unit = choice ( get(x) * B0, put * { y => B2(x, y) } );
-*  def B2(x: a, y: a): unit = choice ( get(x) * B1(y) );
-*  B0
-*}
-*</pre>
-*
-* @see <a href="http://scala.epfl.ch/docu/related.html">PiLib: A Hosted Language for Pi-Calculus Style Concurrency</a>
-* @author Vincent Cremet, Martin Odersky
-*/
+ * Library for using Pi-calculus concurrent primitives in Scala. As an
+ * example, the definition of a two-place buffer using the <code>pilib</code>
+ * library looks like:
+ * <pre>
+ * <b>def</b> Buffer[a](put: Chan[a], get: Chan[a]): unit = {
+ *   <b>def</b> B0: unit = choice ( put * { x => B1(x) } );
+ *   <b>def</b> B1(x: a): unit = choice ( get(x) * B0, put * { y => B2(x, y) } )
+ *   <b>def</b> B2(x: a, y: a): unit = choice ( get(x) * B1(y) )
+ *   B0
+ * }
+ * </pre>
+ *
+ * @see <a href="http://scala.epfl.ch/docu/related.html">PiLib: A Hosted Language for Pi-Calculus Style Concurrency</a>
+ * @author  Vincent Cremet, Martin Odersky
+ * @version 1.0
+ */
 object pilib {
 
   /////////////////////////// SPAWN //////////////////////////////
 
   /**
-  * Run several processes in parallel using the following syntax:
-  * spawn &lt; p_1 | ... | p_n &gt;
-  */
+   * Run several processes in parallel using the following syntax:
+   * <code>spawn &lt; p_1 | ... | p_n &gt;</code>
+   */
   abstract class Spawn {
     def <(p: => unit): Spawn
     def |(p: => unit): Spawn
@@ -56,12 +58,13 @@ object pilib {
   }
 
   /** An untyped guarded process.
-  * @param n         channel name
-  * @param polarity  input (true) or output (false)
-  * @param v         transmitted value
-  * @param c         continuation
-  */
-  case class UGP(n: UChan, polarity: boolean, v: Any, c: Any => Any);
+   *
+   *  @param n         channel name
+   *  @param polarity  input (true) or output (false)
+   *  @param v         transmitted value
+   *  @param c         continuation
+   */
+  case class UGP(n: UChan, polarity: boolean, v: Any, c: Any => Any)
 
   /** Typed guarded process. */
   class GP[a](n: UChan, polarity: boolean, v: Any, c: Any => a) {
@@ -106,8 +109,8 @@ object pilib {
       new Product(this, v)
 
     /** Attach a function to be evaluated at each communication event
-    * on this channel. Replace previous attached function.
-    */
+     *  on this channel. Replace previous attached function.
+     */
     def attach(f: a => unit) =
       log = x => f(x.asInstanceOf[a])
   }
@@ -125,16 +128,18 @@ object pilib {
 
     var initialized = false
 
-    /**
-    * Block if not initialized otherwise continue with the
-    * continuation.
-    */
+    /** Block if not initialized otherwise continue with the
+     *  continuation.
+     */
     def continue = synchronized {
-      if (!initialized) wait();
+      if (!initialized) wait()
       cont()
     }
 
-    /** Set the values of parameters and awake the sleeping sum. */
+    /** Set the values of parameters and awake the sleeping sum.
+     *
+     *  @param f ...
+     */
     def set(f: () => Any) = synchronized {
       cont = f
       initialized = true
@@ -146,7 +151,12 @@ object pilib {
 
   private var sums: List[Sum] = Nil
 
-  /** Test if two lists of guarded processes can communicate. */
+  /** Test if two lists of guarded processes can communicate.
+   *
+   *  @param gs1 ...
+   *  @param gs2 ...
+   *  @return    ...
+   */
   private def matches(gs1: List[UGP], gs2: List[UGP]): Option[Triple[() => unit, () => Any, () => Any]] =
     Pair(gs1, gs2) match {
       case Pair(Nil, _) => None
@@ -160,10 +170,13 @@ object pilib {
         }
     }
 
-  /**
-   * Test if the given sum can react with one of the pending sums.
-   * If yes then do the reaction otherwise append the sum at the end
-   * of the pending sums.
+  /** Test if the given sum can react with one of the pending sums.
+   *  If yes then do the reaction otherwise append the sum at the end
+   *  of the pending sums.
+   *
+   *  @param s1 ...
+   *  @param ss ...
+   *  @return   ...
    */
   private def compare(s1: Sum, ss: List[Sum]): List[Sum] =
     ss match {
@@ -179,10 +192,14 @@ object pilib {
       }
     }
 
-  /** Pi-calculus non-deterministic choice. */
+  /** Pi-calculus non-deterministic choice.
+   *
+   *  @param s ...
+   *  @return  ...
+   */
   def choice[a](s: GP[a]*): a = {
-    val sum = Sum(s.toList map { x => x.untyped });
-    synchronized { sums = compare(sum, sums) };
+    val sum = Sum(s.toList map { x => x.untyped })
+    synchronized { sums = compare(sum, sums) }
     (sum.continue).asInstanceOf[a]
   }
 
diff --git a/src/library/scala/throws.scala b/src/library/scala/throws.scala
index c26559e19c..b9c23b6a5f 100644
--- a/src/library/scala/throws.scala
+++ b/src/library/scala/throws.scala
@@ -9,9 +9,22 @@
 // $Id$
 
 
-package scala;
+package scala
 
 /**
  * Attribute for specifying the exceptions thrown by a method.
+ * <p>
+ *  Example:
+ * </p>
+ * <pre>
+ * <b>class</b> Reader(fname: String) {
+ *   <b>private val</b> in =
+ *     <b>new</b> BufferedReader(<b>new</b> FileReader(fname))
+ *   [throws(classOf[IOException])]
+ *   <b>def</b> read() = in.read()
+ * }</pre>
+ *
+ * @author  Nikolay Mihaylov
+ * @version 1.0, 19/05/2006
  */
-class throws(clazz: java.lang.Class) extends Attribute;
+class throws(clazz: java.lang.Class) extends Attribute