Added some comments and removed inconsistencies.

12 files changed, 255 insertions, 87 deletions

diff --git a/sources/scala/$colon$colon.scala b/sources/scala/$colon$colon.scala
index cb08998724..be151f40d5 100644
--- a/sources/scala/$colon$colon.scala
+++ b/sources/scala/$colon$colon.scala
@@ -1,11 +1,22 @@
-package scala {
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003, LAMP/EPFL                  **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
 
-  /* A non empty list.
-  *
-  */
-  final case class ::[b](hd: b, tl: List[b]) extends List[b] {
+package scala;
+
+
+/** A non empty list characterized by a head and a tail.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 15/07/2003
+ */
+final case class ::[b](hd: b, tl: List[b]) extends List[b] {
     def isEmpty: boolean = false;
     def head: b = hd;
     def tail: List[b] = tl;
-  }
 }
diff --git a/sources/scala/BufferedIterator.scala b/sources/scala/BufferedIterator.scala
index 7885485e6b..7d65973630 100644
--- a/sources/scala/BufferedIterator.scala
+++ b/sources/scala/BufferedIterator.scala
@@ -1,5 +1,26 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003, LAMP/EPFL                  **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
+
 package scala;
 
-trait BufferedIterator[+b] extends Iterator[b] {
-  def head: b;
+
+/** Buffered iterators are iterators which allow to inspect the next
+ *  element without discarding it.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 16/07/2003
+ */
+trait BufferedIterator[+A] extends Iterator[A] {
+
+    /** Checks what the next available element is.
+     *
+     *  @returns the current element
+     */
+    def head: A;
 }
diff --git a/sources/scala/Iterable.scala b/sources/scala/Iterable.scala
index 8543624466..64aff4c8b6 100644
--- a/sources/scala/Iterable.scala
+++ b/sources/scala/Iterable.scala
@@ -4,12 +4,25 @@
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
+** $Id$
 \*                                                                      */
 
-// $Id$
-
 package scala;
 
+
+/** Collection classes supporting this trait provide a method
+ *  <code>elements</code> which returns an iterator over all the
+ *  elements contained in the collection.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 16/07/2003
+ */
 trait Iterable[+A] {
+
+    /** Creates a new iterator over all elements contained in this
+     *  object.
+     *
+     *  @returns the new iterator
+     */
     def elements: Iterator[A];
 }
diff --git a/sources/scala/Iterator.scala b/sources/scala/Iterator.scala
index 3b7a6a9f43..adcc2cf746 100644
--- a/sources/scala/Iterator.scala
+++ b/sources/scala/Iterator.scala
@@ -9,7 +9,56 @@
 
 package scala;
 
-trait Iterator[+a] {
+
+/** The <code>Iterator</code> object provides various functions for
+ *  creating specialized iterators.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 16/07/2003
+ */
+object Iterator {
+
+  def empty[a] = new Iterator[a] {
+    def hasNext = false;
+    def next: a = error("next on empty iterator");
+  }
+
+  def fromArray[a](xs: Array[a]) = new Iterator[a] {
+    private var i = 0;
+    def hasNext: Boolean =
+      i < xs.length;
+    def next: a =
+      if (i < xs.length) { val x = xs(i) ; i = i + 1 ; x }
+      else error("next on empty iterator");
+  }
+
+  def range(lo: Int, hi: Int) = new Iterator[Int] {
+    private var i = 0;
+    def hasNext: Boolean =
+      i <= hi;
+    def next: Int =
+      if (i <= hi) { i = i + 1 ; i - 1 }
+      else error("next on empty iterator");
+  }
+
+  def from(lo: Int) = new Iterator[Int] {
+    private var i = 0;
+    def hasNext: Boolean =
+      true;
+    def next: Int =
+      { i = i + 1 ; i - 1 }
+  }
+}
+
+/** Iterators are data structures that allow to iterate over a sequence
+ *  of elements. They have a <code>hasNext</code> method for checking
+ *  if there is a next element available, and a <code>next</code> method
+ *  which returns the next element and discards it from the iterator.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 16/07/2003
+ */
+trait Iterator[+a] with Iterable[a] {
   def hasNext: Boolean;
   def next: a;
 
@@ -75,41 +124,7 @@ trait Iterator[+a] {
       ahead || Iterator.this.hasNext;
     override def buffered: BufferedIterator[a] = this;
   }
-}
-
-object Iterator {
-
-  def empty[a] = new Iterator[a] {
-    def hasNext = false;
-    def next: a = error("next on empty iterator");
-  }
-
-  def fromArray[a](xs: Array[a]) = new Iterator[a] {
-    private var i = 0;
-    def hasNext: Boolean =
-      i < xs.length;
-    def next: a =
-      if (i < xs.length) { val x = xs(i) ; i = i + 1 ; x }
-      else error("next on empty iterator");
-  }
 
-  def range(lo: Int, hi: Int) = new Iterator[Int] {
-    private var i = 0;
-    def hasNext: Boolean =
-      i <= hi;
-    def next: Int =
-      if (i <= hi) { i = i + 1 ; i - 1 }
-      else error("next on empty iterator");
-  }
-
-  def from(lo: Int) = new Iterator[Int] {
-    private var i = 0;
-    def hasNext: Boolean =
-      true;
-    def next: Int =
-      { i = i + 1 ; i - 1 }
-  }
+  def elements: Iterator[a] = this;
 }
 
-
-
diff --git a/sources/scala/List.scala b/sources/scala/List.scala
index 9c238eb5ae..4c7112ab3e 100644
--- a/sources/scala/List.scala
+++ b/sources/scala/List.scala
@@ -1,18 +1,40 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003, LAMP/EPFL                  **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
+
 package scala;
 
-/* An abstract class representing an ordered collection of elements
-* of type <code>a</code>.
-* This class comes with two implementing case classes {link scala.Nil/} and
-* {@link scala.::_class/} that implement the abstract members <code>isEmpty</code>,
-* <code>head</code> and <code>tail</code>. But instead of this
-*
-* @arg a the type of the elements contained in the list.
-*/
+
+/** This object provides methods for creating specialized lists.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 15/07/2003
+ */
+object List {
+  def range(from: Int, end: Int): List[Int] =
+    if (from >= end) scala.Predef.List()
+    else from :: range(from + 1, end);
+}
+
+/** A trait representing an ordered collection of elements of type
+ *  <code>a</code>. This class comes with two implementing case
+ *  classes <code>scala.Nil</code> and <code>scala.::</code> that
+ *  implement the abstract members <code>isEmpty</code>,
+ *  <code>head</code> and <code>tail</code>.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 16/07/2003
+ */
 trait List[+a] extends Seq[a] {
 
   /** Tests if this list is empty.
-  * @return True iff the list contains no element.
-  */
+   *  @returns true, iff the list contains no element.
+   */
   def isEmpty: Boolean;
 
   /** Returns this first element of the list.
@@ -361,12 +383,3 @@ trait List[+a] extends Seq[a] {
     }
 }
 
-object List {
-
-  def range(from: Int, end: Int): List[Int] =
-    if (from >= end) scala.Predef.List()
-    else from :: range(from + 1, end);
-
-}
-
-
diff --git a/sources/scala/Monitor.scala b/sources/scala/Monitor.scala
index 08e6201612..e2841df582 100644
--- a/sources/scala/Monitor.scala
+++ b/sources/scala/Monitor.scala
@@ -9,10 +9,17 @@
 
 package scala;
 
+
+/** This trait can be used to mix in functionality for synchronizing
+ *  threads on this object.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 11/07/2003
+ */
 trait Monitor {
 
     def synchronized[a](def p: a): a =
-	scala.runtime.NativeMonitor.synchronised(this, p);
+        scala.runtime.NativeMonitor.synchronised(this, p);
 
     def await(def cond: Boolean) = while (!cond) { this.wait() }
 }
diff --git a/sources/scala/Nil.scala b/sources/scala/Nil.scala
index ffede06248..9afbae5f72 100644
--- a/sources/scala/Nil.scala
+++ b/sources/scala/Nil.scala
@@ -1,12 +1,22 @@
-package scala {
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003, LAMP/EPFL                  **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
 
-  /* An empty list. Scala provides <code>[]</code> as syntactic sugar
-  * for <code>Nil</code>.
-  */
-  case object Nil extends List[All] {
+package scala;
+
+
+/** The empty list.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 15/07/2003
+ */
+case object Nil extends List[All] {
     def isEmpty = true;
     def head: All = error("head of empty list");
     def tail: List[All] = error("tail of empty list");
-  }
 }
-
diff --git a/sources/scala/None.scala b/sources/scala/None.scala
index 942bb5a4a6..9905889ac1 100644
--- a/sources/scala/None.scala
+++ b/sources/scala/None.scala
@@ -1,2 +1,18 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2002-2003, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
+
 package scala;
+
+
+/** This case object represents non-existent values.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 16/07/2003
+ */
 case object None extends Option[All];
diff --git a/sources/scala/Option.scala b/sources/scala/Option.scala
index 3a37835bc5..0f373db10c 100644
--- a/sources/scala/Option.scala
+++ b/sources/scala/Option.scala
@@ -1,6 +1,23 @@
-package scala {
-
-  trait Option[+a] {
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2002-2003, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
+
+package scala;
+
+
+/** This class represents optional values. Instances of <code>Option</code>
+ *  are either instances of case class <code>Some</code> or it is case
+ *  object <code>None</code>.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 16/07/2003
+ */
+trait Option[+a] {
 
     def get: a = this match {
       case None => error("None.get")
@@ -31,8 +48,4 @@ package scala {
       case None => Predef.List()
       case Some(x) => Predef.List(x)
     }
-
-    def print: Unit =
-      System.out.println(this.toString())
-  }
 }
diff --git a/sources/scala/PartialFunction.scala b/sources/scala/PartialFunction.scala
index 82edad02cc..e0ed25c0bf 100644
--- a/sources/scala/PartialFunction.scala
+++ b/sources/scala/PartialFunction.scala
@@ -4,13 +4,26 @@
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
+** $Id$
 \*                                                                      */
 
-// $Id$
-
 package scala;
 
 
+/** A partial function of type <code>PartialFunction[A, B]</code> is a
+ *  unary function where the domain does not include all values of type
+ *  <code>A</code>. The function <code>isDefinedAt</code> allows to
+ *  test dynamically, if a value is in the domain of the function.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 16/07/2003
+ */
 trait PartialFunction[-A, +B] with Function1[A, B] {
+
+    /** Checks if a value is contained in the functions domain.
+     *
+     *  @param   x   the value to test
+     *  @returns true, iff <code>x</code> is in the domain of this function.
+     */
     def isDefinedAt(x: A): Boolean;
 }
diff --git a/sources/scala/Seq.scala b/sources/scala/Seq.scala
index f97f4439dc..30db5ec3cf 100644
--- a/sources/scala/Seq.scala
+++ b/sources/scala/Seq.scala
@@ -1,19 +1,39 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2002-2003, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003, LAMP/EPFL                  **
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
+** $Id$
 \*                                                                      */
 
-// $Id$
-
 package scala;
 
-trait Seq[+A] with Function1[Int, A] with Iterable[A] {
 
+/** Class <code>Seq[A]</code> represents finite sequences of elements
+ *  of type <code>A</code>.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 16/07/2003
+ */
+trait Seq[+A] with PartialFunction[Int, A] with Iterable[A] {
+
+    /** Returns the length of the sequence.
+     *
+     *  @returns the sequence length.
+     */
     def length: Int;
 
+    /** Is this partial function defined for the index <code>x</code>?
+     *
+     *  @returns true, iff <code>x</code> is a legal sequence index.
+     */
+    def isDefinedAt(x: Int): Boolean = (x >= 0) && (x < length);
+
+    /** Customizes the <code>toString</code> method.
+     *
+     *  @returns a string representation of this sequence.
+     */
     override def toString() = {
         def toString1(it: Iterator[A]):String = {
 	    if (it.hasNext) {
diff --git a/sources/scala/Some.scala b/sources/scala/Some.scala
index 53040fec44..7c276ac332 100644
--- a/sources/scala/Some.scala
+++ b/sources/scala/Some.scala
@@ -1,3 +1,19 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2002-2003, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
+
 package scala;
-final case class Some[+c](x: c) extends Option[c];
 
+
+/** Class <code>Option[A]</code> represents existing values of type
+ *  <code>A</code>.
+ *
+ *  @author  Martin Odersky
+ *  @version 1.0, 16/07/2003
+ */
+final case class Some[+A](x: A) extends Option[A];