Work on mutable collections docs.

18 files changed, 96 insertions, 71 deletions

diff --git a/src/library/scala/collection/mutable/AddingBuilder.scala b/src/library/scala/collection/mutable/AddingBuilder.scala
index d16a4a71f3..14636c9feb 100644
--- a/src/library/scala/collection/mutable/AddingBuilder.scala
+++ b/src/library/scala/collection/mutable/AddingBuilder.scala
@@ -15,6 +15,7 @@ import generic._
 
 /** The canonical builder for collections that are addable, i.e. that support an efficient `+` method
  *  which adds an element to the collection.
+ *
  *  Collections are built from their empty element using this `+` method.
  *  @param empty  the empty element of the collection.
  *  @tparam Elem  the type of elements that get added to the builder.
diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala
index 0c6aa9ce0c..7dd2af80cb 100644
--- a/src/library/scala/collection/mutable/ArrayBuffer.scala
+++ b/src/library/scala/collection/mutable/ArrayBuffer.scala
@@ -94,11 +94,11 @@ class ArrayBuffer[A](override protected val initialSize: Int)
     this
   }
 
-  /** Prepends a number of elements provided by an iterable object
+  /** Prepends a number of elements provided by a traversable object
    *  via its <code>iterator</code> method. The identity of the
    *  buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs    the traversable object.
    *  @return      the updated buffer.
    */
   override def ++=:(xs: TraversableOnce[A]): this.type = { insertAll(0, xs.toTraversable); this }
@@ -108,7 +108,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
    *  one. Instead, it will insert a new element at index <code>n</code>.
    *
    *  @param n     the index where a new element will be inserted.
-   *  @param iter  the iterable object providing all elements to insert.
+   *  @param seq   the traversable object providing all elements to insert.
    *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
    */
   def insertAll(n: Int, seq: Traversable[A]) {
diff --git a/src/library/scala/collection/mutable/ArrayBuilder.scala b/src/library/scala/collection/mutable/ArrayBuilder.scala
index 7e4bab353b..71f6126735 100644
--- a/src/library/scala/collection/mutable/ArrayBuilder.scala
+++ b/src/library/scala/collection/mutable/ArrayBuilder.scala
@@ -15,7 +15,7 @@ package mutable
 import generic._
 import scala.reflect.ClassManifest
 
-/** A builder class for arrays
+/** A builder class for arrays.
  *
  * @since 2.8
  */
diff --git a/src/library/scala/collection/mutable/ArrayOps.scala b/src/library/scala/collection/mutable/ArrayOps.scala
index 553461c805..3d9d103b06 100644
--- a/src/library/scala/collection/mutable/ArrayOps.scala
+++ b/src/library/scala/collection/mutable/ArrayOps.scala
@@ -14,8 +14,15 @@ package mutable
 
 import scala.reflect.ClassManifest
 
-/**
- * @since 2.8
+/** This class serves as a wrapper for `Array`s with all the operations found in
+ *  indexed sequences. Where needed, instances of arrays are implicitly converted
+ *  into this class.
+ *
+ *  The difference between this class and `WrappedArray` is that calling transformer
+ *  methods such as `filter` and `map` will yield an array, whereas a `WrappedArray`
+ *  will remain a `WrappedArray`.
+ *
+ *  @since 2.8
  */
 abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
 
@@ -31,7 +38,11 @@ abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
       super.toArray[U]
 
   /** Flattens a two-dimensional array by concatenating all its rows
-   *  into a single array
+   *  into a single array.
+   *
+   *  @tparam U        Type of row elements.
+   *  @param asArray   A function that converts elements of this array to rows - arrays of type `U`.
+   *  @return          An array obtained by concatenating rows of this array.
    */
   def flatten[U](implicit asArray: T => /*<:<!!!*/ Array[U]): Array[U] = {
     val b = rowBuilder[U]
@@ -40,7 +51,11 @@ abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
     b.result
   }
 
-  /** Transposes a two dimensional array
+  /** Transposes a two dimensional array.
+   *
+   *  @tparam U       Type of row elements.
+   *  @param asArray  A function that converts elements of this array to rows - arrays of type `U`.
+   *  @return         An array obtained by replacing elements of this arrays with rows the represent.
    */
   def transpose[U](implicit asArray: T => Array[U]): Array[Array[U]] = {
     val bs = asArray(head) map (_ => rowBuilder[U])
diff --git a/src/library/scala/collection/mutable/BufferLike.scala b/src/library/scala/collection/mutable/BufferLike.scala
index 0fb34cc8e0..15e96b2019 100644
--- a/src/library/scala/collection/mutable/BufferLike.scala
+++ b/src/library/scala/collection/mutable/BufferLike.scala
@@ -144,8 +144,8 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
    */
   def append(elems: A*) { appendAll(elems) }
 
-  /** Appends the elements contained in a traversable collection to this buffer.
-   *  @param elems  the collection containing the elements to append.
+  /** Appends the elements contained in a traversable object to this buffer.
+   *  @param xs  the traversable object containing the elements to append.
    */
   def appendAll(xs: TraversableOnce[A]) { this ++= xs }
 
@@ -154,7 +154,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
    */
   def prepend(elems: A*) { prependAll(elems) }
 
-  /** Prepends the elements contained in a traversable collection to this buffer.
+  /** Prepends the elements contained in a traversable object to this buffer.
    *  @param elems  the collection containing the elements to prepend.
    */
   def prependAll(xs: TraversableOnce[A]) { xs ++=: this }
@@ -272,7 +272,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
   /** Adds a number of elements provided by a traversable object and returns
    *  either the collection itself.
    *
-   *  @param iter     the iterable object.
+   *  @param xs     the traversable object.
    */
   @migration(2, 8,
     "As of 2.8, ++ always creates a new collection, even on Buffers.\n"+
diff --git a/src/library/scala/collection/mutable/BufferProxy.scala b/src/library/scala/collection/mutable/BufferProxy.scala
index d4444dab67..71c2bc4ca1 100644
--- a/src/library/scala/collection/mutable/BufferProxy.scala
+++ b/src/library/scala/collection/mutable/BufferProxy.scala
@@ -52,21 +52,21 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
 
   override def readOnly = self.readOnly
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
+  /** Appends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method. The identity of the
    *  buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param iter  the traversable object.
    *  @return      the updated buffer.
    */
   @deprecated("Use ++= instead if you intend to add by side effect to an existing collection.\n"+
               "Use `clone() ++=` if you intend to create a new collection.")
   override def ++(xs: TraversableOnce[A]): Buffer[A] = self.++(xs)
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method.
+  /** Appends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method.
    *
-   *  @param iter  the iterable object.
+   *  @param iter  the traversable object.
    */
   override def ++=(xs: TraversableOnce[A]): this.type = { self.++=(xs); this }
 
@@ -76,10 +76,10 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    */
   override def append(elems: A*) { self.++=(elems) }
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method.
+  /** Appends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method.
    *
-   *  @param iter  the iterable object.
+   *  @param iter  the traversable object.
    */
   override def appendAll(xs: TraversableOnce[A]) { self.appendAll(xs) }
 
@@ -98,11 +98,11 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    */
   override def prepend(elems: A*) { self.prependAll(elems) }
 
-  /** Prepends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
+  /** Prepends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method. The identity of the
    *  buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs  the traversable object.
    */
   override def prependAll(xs: TraversableOnce[A]) { self.prependAll(xs) }
 
diff --git a/src/library/scala/collection/mutable/ConcurrentMap.scala b/src/library/scala/collection/mutable/ConcurrentMap.scala
index 2cfa4f8ae2..10c1f9223b 100644
--- a/src/library/scala/collection/mutable/ConcurrentMap.scala
+++ b/src/library/scala/collection/mutable/ConcurrentMap.scala
@@ -3,6 +3,7 @@ package mutable
 
 /**
  * A template trait for mutable maps that allow concurrent access.
+ *
  * $concurrentmapinfo
  *
  * @tparam A  the key type of the map
diff --git a/src/library/scala/collection/mutable/HashTable.scala b/src/library/scala/collection/mutable/HashTable.scala
index 14f1720a4c..1f6b6152cb 100644
--- a/src/library/scala/collection/mutable/HashTable.scala
+++ b/src/library/scala/collection/mutable/HashTable.scala
@@ -108,7 +108,7 @@ trait HashTable[A] {
 
   private def capacity(expectedSize: Int) = if (expectedSize == 0) 1 else powerOfTwo(expectedSize)
 
-  /** Find entry with given key in table, null if not found
+  /** Find entry with given key in table, null if not found.
    */
   protected def findEntry(key: A): Entry = {
     val h = index(elemHashCode(key))
@@ -129,7 +129,7 @@ trait HashTable[A] {
       resize(2 * table.length)
   }
 
-  /** Remove entry from table if present
+  /** Remove entry from table if present.
    */
   protected def removeEntry(key: A) : Entry = {
     val h = index(elemHashCode(key))
@@ -155,7 +155,7 @@ trait HashTable[A] {
     null
   }
 
-  /** An iterator returning all entries
+  /** An iterator returning all entries.
    */
   protected def entriesIterator: Iterator[Entry] = new Iterator[Entry] {
     val iterTable = table
diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala
index 9c3c1c0e5f..19e67a6731 100644
--- a/src/library/scala/collection/mutable/MapLike.scala
+++ b/src/library/scala/collection/mutable/MapLike.scala
@@ -40,7 +40,7 @@ import annotation.migration
  *    `drop`, `filter` return the same kind of map, you
  *    should also override:
  *  {{{
- *    def> empty: This
+ *    def empty: This
  *  }}}
  *    If you wish to avoid the unnecessary construction of an `Option`
  *    object, you could also override `apply`, `update`,
@@ -187,7 +187,8 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    */
   def clear() { keysIterator foreach -= }
 
-  /** If given key is already in this map, returns associated value
+  /** If given key is already in this map, returns associated value.
+   *
    *  Otherwise, computes value from given expression `op`, stores with key
    *  in map and returns that value.
    *  @param  key the key to test
diff --git a/src/library/scala/collection/mutable/MutableList.scala b/src/library/scala/collection/mutable/MutableList.scala
index 7784927c87..4324fa7ef9 100644
--- a/src/library/scala/collection/mutable/MutableList.scala
+++ b/src/library/scala/collection/mutable/MutableList.scala
@@ -15,12 +15,12 @@ package mutable
 import generic._
 import immutable.{List, Nil}
 
+// !!! todo: convert to LinkedListBuffer?
 /** <p>
  *    This class is used internally to represent mutable lists. It is the
  *     basis for the implementation of the classes
  *     <code>Stack</code>, and <code>Queue</code>.
  *  </p>
- *  !!! todo: convert to LinkedListBuffer?
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
diff --git a/src/library/scala/collection/mutable/OpenHashMap.scala b/src/library/scala/collection/mutable/OpenHashMap.scala
index 79bb96a0bf..cbcc19c3e8 100644
--- a/src/library/scala/collection/mutable/OpenHashMap.scala
+++ b/src/library/scala/collection/mutable/OpenHashMap.scala
@@ -57,6 +57,9 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
   import OpenHashMap.OpenEntry
   type Entry = OpenEntry[Key, Value]
 
+  /**
+   * A default constructor creates a hashmap with initial size 8.
+   */
   def this() = this(8);
 
   override def empty: OpenHashMap[Key, Value] = OpenHashMap.empty[Key, Value]
@@ -212,7 +215,7 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
    *
    * @param  f The function to apply to each key, value mapping.
    */
-  override def foreach[U](f : ((Key, Value)) =>  U){
+  override def foreach[U](f : ((Key, Value)) =>  U) {
     val startModCount = modCount;
     foreachUndeletedEntry(entry => {
       if (modCount != startModCount) error("Concurrent Modification")
diff --git a/src/library/scala/collection/mutable/PriorityQueue.scala b/src/library/scala/collection/mutable/PriorityQueue.scala
index 4d74a2ee74..eade376abe 100644
--- a/src/library/scala/collection/mutable/PriorityQueue.scala
+++ b/src/library/scala/collection/mutable/PriorityQueue.scala
@@ -144,10 +144,10 @@ class PriorityQueue[A](implicit ord: Ordering[A])
     this
   }
 
-  /** Adds all elements provided by an <code>Iterable</code> object
+  /** Adds all elements provided by a `TraversableOnce` object
    *  into the priority queue.
    *
-   *  @param  iter        an iterable object
+   *  @param  xs    an iterable object
    */
   def ++(xs: TraversableOnce[A]) = { this.clone() ++= xs }
 
@@ -206,14 +206,16 @@ class PriorityQueue[A](implicit ord: Ordering[A])
   /**
    * Returns the reverse of this queue. The priority queue that gets
    * returned will have an inversed ordering - if for some elements
-   * <code>x</code> and <code>y</code> the original queue's ordering
-   * had <code>compare</code> returning an integer w, the new one will return -w,
+   * `x` and `y` the original queue's ordering
+   * had `compare` returning an integer ''w'', the new one will return ''-w'',
    * assuming the original ordering abides its contract.
    *
    * Note that the order of the elements will be reversed unless the
-   * <code>compare</code> method returns 0. In this case, such elements
+   * `compare` method returns 0. In this case, such elements
    * will be subsequent, but their corresponding subinterval may be inappropriately
    * reversed. However, due to the compare-equals contract, they will also be equal.
+   *
+   * @return A reversed priority queue.
    */
   override def reverse = {
     val revq = new PriorityQueue[A]()(new math.Ordering[A] {
diff --git a/src/library/scala/collection/mutable/PriorityQueueProxy.scala b/src/library/scala/collection/mutable/PriorityQueueProxy.scala
index 427ffe478a..3f1ee5d217 100644
--- a/src/library/scala/collection/mutable/PriorityQueueProxy.scala
+++ b/src/library/scala/collection/mutable/PriorityQueueProxy.scala
@@ -11,7 +11,7 @@
 package scala.collection
 package mutable
 
-/** This class implements priority queues using a heap. The
+/** This class servers as a proxy for priority queues. The
  *  elements of the queue have to be ordered in terms of the
  *  <code>Ordered[T]</code> class.
  *
diff --git a/src/library/scala/collection/mutable/Stack.scala b/src/library/scala/collection/mutable/Stack.scala
index 45e9fa24b2..c224c030a4 100644
--- a/src/library/scala/collection/mutable/Stack.scala
+++ b/src/library/scala/collection/mutable/Stack.scala
@@ -57,11 +57,11 @@ class Stack[A] private (var elems: List[A]) extends scala.collection.Seq[A] with
    */
   def push(elem1: A, elem2: A, elems: A*): this.type = this.push(elem1).push(elem2).pushAll(elems)
 
-  /** Push all elements provided by the given iterator object onto
-   *  the stack. The last element returned by the iterator
+  /** Push all elements in the given traversable object onto
+   *  the stack. The last element in the traversable object
    *  will be on top of the new stack.
    *
-   *  @param   elems      the iterator object.
+   *  @param xs the traversable object.
    *  @return the stack with the new elements on top.
    */
   def pushAll(xs: TraversableOnce[A]): this.type = { xs foreach push ; this }
diff --git a/src/library/scala/collection/mutable/SynchronizedBuffer.scala b/src/library/scala/collection/mutable/SynchronizedBuffer.scala
index 1c9a77c46a..0fef1a6635 100644
--- a/src/library/scala/collection/mutable/SynchronizedBuffer.scala
+++ b/src/library/scala/collection/mutable/SynchronizedBuffer.scala
@@ -54,18 +54,18 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
     super.+=(elem)
   }
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
-   *  buffer is returned.
+  /** Appends a number of elements provided by a traversable object via
+   *  its `foreach` method.
+   *  The identity of the buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs the traversable object.
    */
   override def ++(xs: TraversableOnce[A]): Self = synchronized {
     super.++(xs)
   }
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method.
+  /** Appends a number of elements provided by a traversable object
+   *  via its `foreach` method.
    *
    *  @param iter  the iterable object.
    */
@@ -81,10 +81,10 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
     super.++=(elems)
   }
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method.
+  /** Appends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method.
    *
-   *  @param iter  the iterable object.
+   *  @param xs the traversable object.
    */
   override def appendAll(xs: TraversableOnce[A]): Unit = synchronized {
     super.appendAll(xs)
@@ -99,11 +99,11 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
     super.+=:(elem)
   }
 
-  /** Prepends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
+  /** Prepends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method. The identity of the
    *  buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs the traversable object.
    */
   override def ++=:(xs: TraversableOnce[A]): this.type = synchronized[this.type] { super.++=:(xs) }
 
@@ -113,11 +113,11 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
    */
   override def prepend(elems: A*): Unit = prependAll(elems)
 
-  /** Prepends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
+  /** Prepends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method. The identity of the
    *  buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs the traversable object.
    */
   override def prependAll(xs: TraversableOnce[A]): Unit = synchronized {
     super.prependAll(xs)
@@ -139,10 +139,10 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
    *  one. Instead, it will insert a new element at index <code>n</code>.
    *
    *  @param n     the index where a new element will be inserted.
-   *  @param iter  the iterable object providing all elements to insert.
+   *  @param xs    the traversable object providing all elements to insert.
    */
-  abstract override def insertAll(n: Int, iter: Traversable[A]): Unit = synchronized {
-     super.insertAll(n, iter)
+  abstract override def insertAll(n: Int, xs: Traversable[A]): Unit = synchronized {
+     super.insertAll(n, xs)
   }
 
   /** Replace element at index <code>n</code> with the new element
diff --git a/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala b/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
index 9d18846252..933b3b41a4 100644
--- a/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
+++ b/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
@@ -12,7 +12,7 @@
 package scala.collection
 package mutable
 
-/** This class implements synchronized priority queues using a heap.
+/** This class implements synchronized priority queues using a binary heap.
  *  The elements of the queue have to be ordered in terms of the
  *  <code>Ordered[T]</code> class.
  *
@@ -39,13 +39,13 @@ class SynchronizedPriorityQueue[A](implicit ord: Ordering[A]) extends PriorityQu
     this
   }
 
-  /** Adds all elements provided by an iterator into the priority queue.
+  /** Adds all elements of a traversable object into the priority queue.
    *
-   *  @param  it        an iterator
+   *  @param  xs        a traversable object
    */
-  override def ++=(it: TraversableOnce[A]): this.type = {
+  override def ++=(xs: TraversableOnce[A]): this.type = {
     synchronized {
-      super.++=(it)
+      super.++=(xs)
     }
     this
   }
diff --git a/src/library/scala/collection/mutable/SynchronizedQueue.scala b/src/library/scala/collection/mutable/SynchronizedQueue.scala
index e7630cee06..b09687a78e 100644
--- a/src/library/scala/collection/mutable/SynchronizedQueue.scala
+++ b/src/library/scala/collection/mutable/SynchronizedQueue.scala
@@ -36,11 +36,11 @@ class SynchronizedQueue[A] extends Queue[A] {
    */
   override def +=(elem: A): this.type = synchronized[this.type] { super.+=(elem) }
 
-  /** Adds all elements provided by an <code>Iterable</code> object
+  /** Adds all elements provided by a `TraversableOnce` 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
+   *  @param  xs        a traversable object
    */
   override def ++=(xs: TraversableOnce[A]): this.type = synchronized[this.type] { super.++=(xs) }
 
diff --git a/src/library/scala/collection/mutable/SynchronizedStack.scala b/src/library/scala/collection/mutable/SynchronizedStack.scala
index 4394d307eb..4940884302 100644
--- a/src/library/scala/collection/mutable/SynchronizedStack.scala
+++ b/src/library/scala/collection/mutable/SynchronizedStack.scala
@@ -39,16 +39,18 @@ class SynchronizedStack[A] extends Stack[A] {
   /** Push two or more elements onto the stack. The last element
    *  of the sequence will be on top of the new stack.
    *
-   *  @param   elems      the element sequence.
-   *  @return the stack with the new elements on top.
+   *  @param elem1      the first element to push.
+   *  @param elem2      the second element to push.
+   *  @param elems      the element sequence that will be pushed.
+   *  @return           the stack with the new elements on top.
    */
   override def push(elem1: A, elem2: A, elems: A*): this.type = synchronized[this.type] { super.push(elem1, elem2, elems: _*) }
 
-  /** Pushes all elements provided by an iterator
-   *  on top of the stack. The elements are pushed in the order they
-   *  are given out by the iterator.
+  /** Pushes all elements provided by a traversable object
+   *  on top of the stack. The elements are pushed in the order the
+   *  traversable object is traversed.
    *
-   *  @param  elems        an iterator
+   *  @param  xs        a traversable object
    */
   override def pushAll(xs: TraversableOnce[A]): this.type = synchronized[this.type] { super.pushAll(elems) }