Changed names in all the files and started to a...

Changed names in all the files and started to add some comments. The
collection classes do not yet compile.

34 files changed, 374 insertions, 90 deletions

diff --git a/sources/scala/collection/Map.scala b/sources/scala/collection/Map.scala
index 049f4a6998..f0b4788161 100644
--- a/sources/scala/collection/Map.scala
+++ b/sources/scala/collection/Map.scala
@@ -7,9 +7,22 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection;
 
-/** I promise, there will be some documentation soon! :-) Matthias
+
+/** This trait defines the interface of collections that unambiguously map
+ *  keys to values (i.e. a key is mapped to at least one value).
+ *  Trait <code>Map</code> may only be used for
+ *  accessing elements from map implementations. Two different extensions
+ *  of trait <code>Map</code> in the package <code>scala.collections.mutable</code>
+ *  and  <code>scala.collections.immutable</code> provide functionality for
+ *  adding new key/value mappings to a map. The trait in the first package is
+ *  implemented by maps that are modified destructively, whereas the trait in
+ *  the second package is used by functional map implementations that rely on
+ *  immutable data structures.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
  */
 trait Map[A, +B] with PartialFunction[A, B]
                  with Iterable[Pair[A, B]] {
diff --git a/sources/scala/collection/Set.scala b/sources/scala/collection/Set.scala
index 3f9912d984..080a198e0e 100644
--- a/sources/scala/collection/Set.scala
+++ b/sources/scala/collection/Set.scala
@@ -7,9 +7,22 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection;
 
 
+/** This trait defines the interface of collections that do not contain
+ *  duplicate elements. Trait <code>Set</code> may only be used for
+ *  accessing elements from set implementations. Two different extensions
+ *  of trait <code>Set</code> in the package <code>scala.collections.mutable</code>
+ *  and  <code>scala.collections.immutable</code> provide functionality for
+ *  adding new elements to a set. The trait in the first package is implemented
+ *  by sets the are modified destructively, whereas the trait in the second
+ *  package is used by functional set implementations that rely on immutable
+ *  data structures.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 trait Set[A] with Iterable[A] {
 
     def size: Int;
diff --git a/sources/scala/collection/immutable/ListMap.scala b/sources/scala/collection/immutable/ListMap.scala
index 814e42799f..ce21acbfc4 100644
--- a/sources/scala/collection/immutable/ListMap.scala
+++ b/sources/scala/collection/immutable/ListMap.scala
@@ -9,10 +9,10 @@
 // $Id$
 
 
-package scala;
+package scala.collections.immutable;
 
 
-class ListMap[A, B] extends MutableMap[A, B] with DefaultMapModel[A, B] {
+class ListMap[A, B] extends Map[A, B] with DefaultMapModel[A, B] {
 
     var xs: List[Entry] = Nil;
 
diff --git a/sources/scala/collection/immutable/ListSet.scala b/sources/scala/collection/immutable/ListSet.scala
index 970308db2c..9676fd2dd8 100644
--- a/sources/scala/collection/immutable/ListSet.scala
+++ b/sources/scala/collection/immutable/ListSet.scala
@@ -4,16 +4,15 @@
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
+** $Id$
 \*                                                                      */
 
-// $Id$
 
-
-package scala;
+package scala.collection.immutable;
 
 /** I promise, there will be some documentation soon! :-) Matthias
  */
-class ListSet[A] extends MutableSet[A] {
+class ListSet[A] extends Set[A] {
 
     protected var elems: List[A] = Nil;
 
diff --git a/sources/scala/collection/immutable/Map.scala b/sources/scala/collection/immutable/Map.scala
index 7182d18e78..10e3b7b733 100644
--- a/sources/scala/collection/immutable/Map.scala
+++ b/sources/scala/collection/immutable/Map.scala
@@ -7,9 +7,10 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.immutable;
 
-trait ImmutableMap[A, B, This <: ImmutableMap[A, B, This]]: This with Map[A, B] {
+
+trait Map[A, B, This <: scala.collection.immutable.Map[A, B, This]]: This with scala.collection.Map[A, B] {
 
     def update(key: A, value: B): This;
 
diff --git a/sources/scala/collection/immutable/Set.scala b/sources/scala/collection/immutable/Set.scala
index 7e59d8dbaf..1968834144 100644
--- a/sources/scala/collection/immutable/Set.scala
+++ b/sources/scala/collection/immutable/Set.scala
@@ -7,10 +7,10 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.immutable;
 
 
-trait ImmutableSet[A, This <: ImmutableSet[A, This]]: This with Set[A] {
+trait Set[A, This <: ImmutableSet[A, This]]: This with scala.collection.Set[A] {
 
     def add(elem: A): This;
 
diff --git a/sources/scala/collection/mutable/Buffer.scala b/sources/scala/collection/mutable/Buffer.scala
index 62efe1b7c4..654a4560fb 100644
--- a/sources/scala/collection/mutable/Buffer.scala
+++ b/sources/scala/collection/mutable/Buffer.scala
@@ -7,10 +7,18 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
-class Buffer[A] with MutableList[A] {
+/** Buffers are used to create sequences of elements incrementally by
+ *  appending or prepending new elements. It is also possible to
+ *  access and modify elements in a random access fashion via the
+ *  index of the element in the sequence.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
+class Buffer[A] with scala.collection.mutable.List[A] {
 
     def prepend(elem: A) = prependElem(elem);
 
diff --git a/sources/scala/collection/mutable/DefaultMapModel.scala b/sources/scala/collection/mutable/DefaultMapModel.scala
index 2e272dc59b..7da241c83f 100644
--- a/sources/scala/collection/mutable/DefaultMapModel.scala
+++ b/sources/scala/collection/mutable/DefaultMapModel.scala
@@ -4,15 +4,20 @@
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
+** $Id$
 \*                                                                      */
 
-// $Id$
+package scala.collection.mutable;
 
 
-package scala;
-
-
-trait DefaultMapModel[A, B] extends MutableMap[A, B] {
+/** This trait is used internally. It implements the mutable <code>Map</code>
+ *  trait in terms of three functions: <code>findEntry</code>, <code>addEntry</code>,
+ *  and <code>entries</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
+trait DefaultMapModel[A, B] extends scala.collection.mutable.Map[A, B] {
 
 	protected def findEntry(key: A): Option[Entry];
 
diff --git a/sources/scala/collection/mutable/DoubleLinkedList.scala b/sources/scala/collection/mutable/DoubleLinkedList.scala
index 800db9d158..b21b67b560 100644
--- a/sources/scala/collection/mutable/DoubleLinkedList.scala
+++ b/sources/scala/collection/mutable/DoubleLinkedList.scala
@@ -7,9 +7,16 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
-
+package scala.collection.mutable;
 
+/** This extensible class may be used as a basis for implementing double
+ *  linked lists. Type variable <code>A</code> refers to the element type
+ *  of the list, type variable <code>This</code> is used to model self
+ *  types of linked lists.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 abstract class DoubleLinkedList[A, This <: DoubleLinkedList[A, This]]: This
 	extends SingleLinkedList[A, This] {
 
diff --git a/sources/scala/collection/mutable/HashMap.scala b/sources/scala/collection/mutable/HashMap.scala
index fd5ba85580..e25d94be2f 100644
--- a/sources/scala/collection/mutable/HashMap.scala
+++ b/sources/scala/collection/mutable/HashMap.scala
@@ -7,11 +7,14 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
-/** I promise, there will be some documentation soon! :-) Matthias
+/** This class implements mutable maps using a hashtable.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
  */
-class HashMap[A, B] extends MutableMap[A, B]
+class HashMap[A, B] extends scala.collection.mutable.Map[A, B]
                     with HashTable[A]
                     with DefaultMapModel[A, B] {
 
diff --git a/sources/scala/collection/mutable/HashSet.scala b/sources/scala/collection/mutable/HashSet.scala
index 55d01dc54a..8b68a9aa9d 100644
--- a/sources/scala/collection/mutable/HashSet.scala
+++ b/sources/scala/collection/mutable/HashSet.scala
@@ -7,11 +7,15 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
-/** I promise, there will be some documentation soon! :-) Matthias
+
+/** This class implements mutable sets using a hashtable.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
  */
-class HashSet[A] extends MutableSet[A] with HashTable[A] {
+class HashSet[A] extends scala.collection.mutable.Set[A] with HashTable[A] {
 
     def contains(elem: A): Boolean = findEntry(elem) match {
         case None => false
diff --git a/sources/scala/collection/mutable/HashTable.scala b/sources/scala/collection/mutable/HashTable.scala
index caae9f2f98..a9f306161d 100644
--- a/sources/scala/collection/mutable/HashTable.scala
+++ b/sources/scala/collection/mutable/HashTable.scala
@@ -7,9 +7,25 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
-
-/** I promise, there will be some documentation soon! :-) Matthias
+package scala.collection.mutable;
+
+
+/** This class can be used to construct data structures that are based
+ *  on hashtables. Class <code>HashTable[A]</code> implements a hashtable
+ *  that maps keys of type <code>A</code> to values of the fully abstract
+ *  member type <code>Entry</code>. Classes that make use of <code>HashTable</code>
+ *  have to provide an implementation for <code>Entry</code> and implement the
+ *  function <code>entryKey</code>.<p>
+ *
+ *  There are mainly two parameters that affect the performance of a hashtable:
+ *  the <i>initial size</i> and the <i>load factor</i>. The <i>size</i>
+ *  refers to the number of <i>buckets</i> in the hashtable, and the <i>load
+ *  factor</i> is a measure of how full the hashtable is allowed to get before
+ *  its size is automatically doubled. Both parameters may be changed by
+ *  overriding the corresponding values in class <code>HashTable</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
  */
 abstract class HashTable[A] {
 
diff --git a/sources/scala/collection/mutable/History.scala b/sources/scala/collection/mutable/History.scala
index 115fb850dc..b56f231862 100644
--- a/sources/scala/collection/mutable/History.scala
+++ b/sources/scala/collection/mutable/History.scala
@@ -7,13 +7,16 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
-/** <tt>History[A, B]</tt> objects may subscribe to events of
- *  type <tt>A</tt> published by an object of type <tt>B</tt>.
+/** <code>History[A, B]</code> objects may subscribe to events of
+ *  type <code>A</code> published by an object of type <code>B</code>.
  *  The history subscriber object records all published events
- *  up to maximum number of <tt>maxHistory</tt> events.
+ *  up to maximum number of <code>maxHistory</code> events.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
  */
 class History[A, B] with Subscriber[A, B] {
 
diff --git a/sources/scala/collection/mutable/Inclusion.scala b/sources/scala/collection/mutable/Inclusion.scala
index 52ee525d08..e93f429095 100644
--- a/sources/scala/collection/mutable/Inclusion.scala
+++ b/sources/scala/collection/mutable/Inclusion.scala
@@ -7,7 +7,12 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
-
+package scala.collection.mutable;
 
+/** This observable update refers to inclusion operations that add new elements
+ *  to collection classes.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 case class Inclusion[A](elem: A) extends ObservableUpdate[A];
diff --git a/sources/scala/collection/mutable/LinkedList.scala b/sources/scala/collection/mutable/LinkedList.scala
index 380acdb1be..1f38d894f6 100644
--- a/sources/scala/collection/mutable/LinkedList.scala
+++ b/sources/scala/collection/mutable/LinkedList.scala
@@ -7,7 +7,14 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
+
+/** This class implements single linked lists where both the head (<code>elem</code>)
+ *  and the tail (<code>next</code>) are mutable.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 
 class LinkedList[A](head: A, tail: LinkedList[A]) extends SingleLinkedList[A, LinkedList[A]] {
 	elem = head;
diff --git a/sources/scala/collection/mutable/List.scala b/sources/scala/collection/mutable/List.scala
index d15b6c3739..1c8634c751 100644
--- a/sources/scala/collection/mutable/List.scala
+++ b/sources/scala/collection/mutable/List.scala
@@ -7,10 +7,16 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
-
-class MutableList[A] with Seq[A] with PartialFunction[Int, A] {
+/** This class is used internally to represent mutable lists. It is the
+ *  basis for the implementation of the classes <code>Buffer</code>,
+ *  <code>Stack</code>, and <code>Queue</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
+class List[A] with Seq[A] with PartialFunction[Int, A] {
 
     protected var first: LinkedList[A] = null;
     protected var last: LinkedList[A] = null;
diff --git a/sources/scala/collection/mutable/Map.scala b/sources/scala/collection/mutable/Map.scala
index 3533edcc47..c9ae318b3b 100644
--- a/sources/scala/collection/mutable/Map.scala
+++ b/sources/scala/collection/mutable/Map.scala
@@ -7,11 +7,18 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
-/** I promise, there will be some documentation soon! :-) Matthias
+
+/** This trait represents mutable maps. Concrete map implementations
+ *  just have to provide functionality for the abstract methods in
+ *  <code>scala.collection.Map</code> as well as for <code>update</code>,
+ *  and <code>remove</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
  */
-trait MutableMap[A, B] with Map[A, B] {
+trait Map[A, B] with scala.collection.Map[A, B] {
 
     def update(key: A, value: B): Unit;
 
diff --git a/sources/scala/collection/mutable/Modification.scala b/sources/scala/collection/mutable/Modification.scala
index 4da13bd61a..d83f445bee 100644
--- a/sources/scala/collection/mutable/Modification.scala
+++ b/sources/scala/collection/mutable/Modification.scala
@@ -7,7 +7,12 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
-
+package scala.collection.mutable;
 
+/** This observable update refers to destructive modification operations
+ *  of elements from collection classes.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 case class Modification[A](old: A, nu: A) extends ObservableUpdate[A];
diff --git a/sources/scala/collection/mutable/MultiMap.scala b/sources/scala/collection/mutable/MultiMap.scala
index 7bc6cc2518..130fd64442 100644
--- a/sources/scala/collection/mutable/MultiMap.scala
+++ b/sources/scala/collection/mutable/MultiMap.scala
@@ -7,11 +7,17 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
-
-trait MultiMap[A, B] extends MutableMap[A, MutableSet[B]] {
-    protected def makeSet: MutableSet[B] = new HashSet[B];
+/** This class is typically used as a mixin. It turns maps which map <code>A</code>
+ *  to <code>Set[B]</code> objects into multi maps which map <code>A</code> to
+ *  <code>B</code> objects.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
+trait MultiMap[A, B] extends scala.collection.mutable.Map[A, scala.collection.mutable.Set[B]] {
+    protected def makeSet: scala.collection.mutable.Set[B] = new HashSet[B];
 
     def add(key: A, value: B): Unit = get(key) match {
         case None => val set = makeSet;
diff --git a/sources/scala/collection/mutable/ObservableMap.scala b/sources/scala/collection/mutable/ObservableMap.scala
index 420a0feeaa..d28284a9b9 100644
--- a/sources/scala/collection/mutable/ObservableMap.scala
+++ b/sources/scala/collection/mutable/ObservableMap.scala
@@ -7,11 +7,19 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
+/** This class is typically used as a mixin. It adds a subscription
+ *  mechanism to the <code>Map</code> class into which this abstract
+ *  class is mixed in. Class <code>ObservableMap</code> publishes
+ *  events of the type <code>ObservableUpdate</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 abstract class ObservableMap[A, B, This <: ObservableMap[A, B, This]]: This
-                    extends MutableMap[A, B]
+                    extends scala.collection.mutable.Map[A, B]
                     with Publisher[ObservableUpdate[Pair[A, B]] with Undo, This] {
 
     override def update(key: A, value: B): Unit = get(key) match {
diff --git a/sources/scala/collection/mutable/ObservableSet.scala b/sources/scala/collection/mutable/ObservableSet.scala
index c862c33648..4741087962 100644
--- a/sources/scala/collection/mutable/ObservableSet.scala
+++ b/sources/scala/collection/mutable/ObservableSet.scala
@@ -7,11 +7,18 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
-
+package scala.collection.mutable;
 
+/** This class is typically used as a mixin. It adds a subscription
+ *  mechanism to the <code>Set</code> class into which this abstract
+ *  class is mixed in. Class <code>ObservableSet</code> publishes
+ *  events of the type <code>ObservableUpdate</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 abstract class ObservableSet[A, This <: ObservableSet[A, This]]: This
-                    extends MutableSet[A]
+                    extends scala.collection.mutable.Set[A]
                     with Publisher[ObservableUpdate[A] with Undo, This] {
 
     override def add(elem: A): Unit = if (!contains(elem)) {
diff --git a/sources/scala/collection/mutable/ObservableUpdate.scala b/sources/scala/collection/mutable/ObservableUpdate.scala
index fabe049f40..f79a53d5a1 100644
--- a/sources/scala/collection/mutable/ObservableUpdate.scala
+++ b/sources/scala/collection/mutable/ObservableUpdate.scala
@@ -7,7 +7,14 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
-
+package scala.collection.mutable;
 
+/** Observable update events are issued by observable collection classes
+ *  whenever a data structure is changed. Class <code>ObservableUpdate</code>
+ *  has several subclasses for the various kinds of events: <code>Modification</code>
+ *  <code>Removal</code>, <code>Insertion</code>, and <code>Reset</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 trait ObservableUpdate[+A];
diff --git a/sources/scala/collection/mutable/Publisher.scala b/sources/scala/collection/mutable/Publisher.scala
index 5d6df1f140..6e2e371e32 100644
--- a/sources/scala/collection/mutable/Publisher.scala
+++ b/sources/scala/collection/mutable/Publisher.scala
@@ -7,14 +7,22 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
-
-
-/** <tt>Publisher[A, This]</tt> objects publish events of type <tt>A</tt>
- *  to all registered subscribers.
+package scala.collection.mutable;
+
+
+/** <code>Publisher[A,This]</code> objects publish events of type <code>A</code>
+ *  to all registered subscribers. When subscribing, a subscriber may specify
+ *  a filter which can be used to constrain the number of events sent to the
+ *  subscriber. Subscribers may suspend their subscription, or reactivate a
+ *  suspended subscription. Class <code>Publisher</code> is typically used
+ *  as a mixin. The type variable <code>This</code> models self types.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
  */
 class Publisher[A, This <: Publisher[A, This]]: This {
-    private val filters = new HashMap[Subscriber[A, This], MutableSet[A => Boolean]]
+    private val filters = new HashMap[Subscriber[A, This],
+                                      scala.collection.mutable.Set[A => Boolean]]
                             with MultiMap[Subscriber[A, This], A => Boolean];
     private val suspended = new HashSet[Subscriber[A, This]];
 
diff --git a/sources/scala/collection/mutable/Queue.scala b/sources/scala/collection/mutable/Queue.scala
index 7ab2011bea..91c6d8b3c7 100644
--- a/sources/scala/collection/mutable/Queue.scala
+++ b/sources/scala/collection/mutable/Queue.scala
@@ -7,17 +7,47 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
+/** <code>Queue</code> objects implement data structures that allow to
+ *  insert and retrieve elements in a first-in-first-out (FIFO) manner.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
+class Queue[A] with scala.collection.mutable.List[A] {
 
-class Queue[A] with MutableList[A] {
+    /** Checks if the queue is empty.
+     *
+     *  @returns true, iff there is no element in the queue.
+     */
+    def isEmpty: Boolean = (first == null);
 
+    /** Inserts a single element at the end of the queue.
+     *
+     *  @param  elem        the element to insert
+     */
     def +=(elem: A) = appendElem(elem);
 
+    /** Adds all elements provided by an <code>Iterable</code> object
+     *  at the end of the queue. The elements are prepended in the order they
+     *  are given out by the iterator.
+     *
+     *  @param  iter        an iterable object
+     */
     def +=(iter: Iterable[A]) = iter.elements.foreach(e => appendElem(e));
 
+    /** Adds all elements to the queue.
+     *
+     *  @param  elems		the elements to add.
+     */
     def enqueue(elems: A*): Unit = (this += elems);
 
+    /** Returns the first element in the queue, and removes this element
+     *  from the queue.
+     *
+     *  @returns the first element of the queue.
+     */
     def dequeue: A = {
         if (first == null)
             error("queue empty");
@@ -28,5 +58,15 @@ class Queue[A] with MutableList[A] {
         }
     }
 
+    /** Returns the first element in the queue, or throws an error if there
+     *  is no element contained in the queue.
+     *
+     *  @returns the first element.
+     */
+    def first: A = first.elem;
+
+    /** Removes all elements from the queue. After this operation is completed,
+     *  the queue will be empty.
+     */
     def clear: Unit = reset;
 }
diff --git a/sources/scala/collection/mutable/Removal.scala b/sources/scala/collection/mutable/Removal.scala
index 37b062709e..4e2b9b921d 100644
--- a/sources/scala/collection/mutable/Removal.scala
+++ b/sources/scala/collection/mutable/Removal.scala
@@ -7,7 +7,13 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
+/** This observable update refers to removal operations of elements
+ *  from collection classes.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 case class Removal[A](elem: A) extends ObservableUpdate[A];
diff --git a/sources/scala/collection/mutable/Reset.scala b/sources/scala/collection/mutable/Reset.scala
index b458560251..9caabe73e6 100644
--- a/sources/scala/collection/mutable/Reset.scala
+++ b/sources/scala/collection/mutable/Reset.scala
@@ -7,7 +7,11 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
-
+package scala.collection.mutable;
 
+/** This observable update refers to reset operations.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 case class Reset[A]() extends ObservableUpdate[A];
diff --git a/sources/scala/collection/mutable/RevertableHistory.scala b/sources/scala/collection/mutable/RevertableHistory.scala
index 760f5dcea6..9358e3f476 100644
--- a/sources/scala/collection/mutable/RevertableHistory.scala
+++ b/sources/scala/collection/mutable/RevertableHistory.scala
@@ -7,14 +7,21 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
-/** <tt>Subscriber[-A, -B]</tt> objects may subscribe to events of
- *  type <tt>A</tt> published by an object of type <tt>B</tt>.
+/** A revertable history is a <code>History</code> object which supports
+ *  an undo operation. Type variable <code>A</code> refers to the type
+ *  of the published events, <code>B</code> denotes the publisher type.
+ *  Type <code>B</code> is typically a subtype of <code>Publisher</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
  */
 class RevertableHistory[A <: Undo, B] extends History[A, B] with Undo {
 
+    /** Rollback the full history.
+     */
     def undo: Unit = {
     	val old = log.toList.reverse;
     	clear;
diff --git a/sources/scala/collection/mutable/Set.scala b/sources/scala/collection/mutable/Set.scala
index c64104989d..688130b156 100644
--- a/sources/scala/collection/mutable/Set.scala
+++ b/sources/scala/collection/mutable/Set.scala
@@ -7,10 +7,18 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
-trait MutableSet[A] with Set[A] {
+/** This trait represents mutable sets. Concrete set implementations
+ *  just have to provide functionality for the abstract methods in
+ *  <code>scala.collection.Set</code> as well as for <code>add</code>,
+ *  <code>remove</code>, and <code>clear</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
+trait Set[A] with scala.collection.Set[A] {
 
     def add(elem: A): Unit;
 
@@ -29,7 +37,7 @@ trait MutableSet[A] with Set[A] {
     def removeSet(that: Iterable[A]): Unit =
         that.elements.foreach(elem => remove(elem));
 
-    def intersect(that: Set[A]): Unit = filter(that.contains);
+    def intersect(that: scala.collection.Set[A]): Unit = filter(that.contains);
 
     def clear: Unit;
 
diff --git a/sources/scala/collection/mutable/SingleLinkedList.scala b/sources/scala/collection/mutable/SingleLinkedList.scala
index 5fd2fe937c..edeb0db261 100644
--- a/sources/scala/collection/mutable/SingleLinkedList.scala
+++ b/sources/scala/collection/mutable/SingleLinkedList.scala
@@ -4,14 +4,20 @@
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
+** $Id$
 \*                                                                      */
 
-// $Id$
-
-
-package scala;
+package scala.collection.mutable;
 
 
+/** This extensible class may be used as a basis for implementing linked
+ *  list. Type variable <code>A</code> refers to the element type of the
+ *  list, type variable <code>This</code> is used to model self types of
+ *  linked lists.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 abstract class SingleLinkedList[A, This <: SingleLinkedList[A, This]]: This with Seq[A] {
 
     var elem: A = _;
diff --git a/sources/scala/collection/mutable/Stack.scala b/sources/scala/collection/mutable/Stack.scala
index 67f1065aef..6b19a3dd3c 100644
--- a/sources/scala/collection/mutable/Stack.scala
+++ b/sources/scala/collection/mutable/Stack.scala
@@ -7,24 +7,74 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
-class Stack[A] with MutableList[A] {
+/** A stack implements a data structure which allows to store and retrieve
+ *  objects in a last-in-first-out (LIFO) fashion.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
+class Stack[A] with scala.collection.mutable.List[A] with Iterable[A] {
 
-    def +=(elem: A) = prependElem(elem);
+    /** Checks if the stack is empty.
+     *
+     *  @returns true, iff there is no element on the stack
+     */
+    def isEmpty: Boolean = (first == null);
 
-    def +=(iter: Iterable[A]) = iter.elements.foreach(e => prependElem(e));
+    /** Pushes a single element on top of the stack.
+     *
+     *  @param  elem		the element to push onto the stack
+     */
+    def +=(elem: A): Unit = prependElem(elem);
 
+    /** Pushes all elements provided by an <code>Iterable</code> object
+     *  on top of the stack. The elements are pushed in the order they
+     *  are given out by the iterator.
+     *
+     *  @param  iter		an iterable object
+     */
+    def +=(iter: Iterable[A]): Unit = iter.elements.foreach(e => prependElem(e));
+
+    /** Pushes a sequence of elements on top of the stack. The first element
+     *  is pushed first, etc.
+     *
+     *  @param  elems		a sequence of elements
+     */
     def push(elems: A*): Unit = (this += elems);
 
+    /** Returns the top element of the stack. This method will not remove
+     *  the element from the stack. An error is signaled if there is no
+     *  element on the stack.
+     *
+     *  @returns the top element
+     */
     def top: A = if (first == null) error("stack empty"); else first.elem;
 
+    /** Removes the top element from the stack.
+     */
     def pop: Unit = if (first != null) { first = first.next; }
 
+    /** Removes all elements from the stack. After this operation completed,
+     *  the stack will be empty.
+     */
     def clear: Unit = reset;
 
+    /** Returns an iterator over all elements on the stack. This iterator
+     *  is stable with respect to state changes in the stack object; i.e.
+     *  such changes will not be reflected in the iterator. The iterator
+     *  issues elements in the order they were inserted into the stack
+     *  (FIFO order).
+     *
+     *  @returns an iterator over all stack elements.
+     */
     override def elements: Iterator[A] = toList.elements;
 
+    /** Creates a list of all stack elements in FIFO order.
+     *
+     *  @returns the created list.
+     */
     override def toList: List[A] = super.toList.reverse;
 }
diff --git a/sources/scala/collection/mutable/Subscriber.scala b/sources/scala/collection/mutable/Subscriber.scala
index f41dd3e44d..c62c09fb49 100644
--- a/sources/scala/collection/mutable/Subscriber.scala
+++ b/sources/scala/collection/mutable/Subscriber.scala
@@ -7,11 +7,15 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
-/** <tt>Subscriber[-A, -B]</tt> objects may subscribe to events of
- *  type <tt>A</tt> published by an object of type <tt>B</tt>.
+/** <code>Subscriber[A, B]</code> objects may subscribe to events of
+ *  type <code>A</code> published by an object of type <code>B</code>.
+ *  <code>B</code> is typically a subtype of <code>Publisher</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
  */
 trait Subscriber[-A, -B] {
     def update(pub: B, event: A): Unit;
diff --git a/sources/scala/collection/mutable/SynchronizedMap.scala b/sources/scala/collection/mutable/SynchronizedMap.scala
index a710fcf761..40a1e4e959 100644
--- a/sources/scala/collection/mutable/SynchronizedMap.scala
+++ b/sources/scala/collection/mutable/SynchronizedMap.scala
@@ -7,10 +7,16 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
-trait SynchronizedMap[A, B] extends MutableMap[A, B] with Monitor {
+/** This trait should be used as a mixin. It synchronizes the <code>Map</code>
+ *  functions of the class into which it is mixed in.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
+trait SynchronizedMap[A, B] extends scala.collection.mutable.Map[A, B] with Monitor {
 
     override def size: Int = synchronized {
         super.size;
diff --git a/sources/scala/collection/mutable/SynchronizedSet.scala b/sources/scala/collection/mutable/SynchronizedSet.scala
index 1e0600afa9..a13f6ec288 100644
--- a/sources/scala/collection/mutable/SynchronizedSet.scala
+++ b/sources/scala/collection/mutable/SynchronizedSet.scala
@@ -7,10 +7,16 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
-trait SynchronizedSet[A] extends MutableSet[A] with Monitor {
+/** This trait should be used as a mixin. It synchronizes the <code>Set</code>
+ *  functions of the class into which it is mixed in.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
+trait SynchronizedSet[A] extends scala.collection.mutable.Set[A] with Monitor {
 
     override def size: Int = synchronized {
         super.size
diff --git a/sources/scala/collection/mutable/Undo.scala b/sources/scala/collection/mutable/Undo.scala
index 4349851e5a..f67ba946b8 100644
--- a/sources/scala/collection/mutable/Undo.scala
+++ b/sources/scala/collection/mutable/Undo.scala
@@ -7,9 +7,18 @@
 ** $Id$
 \*                                                                      */
 
-package scala;
+package scala.collection.mutable;
 
 
+/** Classes that implement the <code>Undo</code> trait provide an operation
+ *  <code>undo</code> which can be used to undo the last operation.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.0, 08/07/2003
+ */
 trait Undo {
+
+    /** Undo the last operation.
+     */
     def undo: Unit;
 }