docs. no review

12 files changed, 166 insertions, 70 deletions

diff --git a/src/library/scala/collection/BitSet.scala b/src/library/scala/collection/BitSet.scala
index 59acb2922e..b43b681888 100644
--- a/src/library/scala/collection/BitSet.scala
+++ b/src/library/scala/collection/BitSet.scala
@@ -23,6 +23,7 @@ trait BitSet extends Set[Int]
 
 /** $factoryInfo
  *  @define coll bitset
+ *  @define Coll BitSet
  */
 object BitSet extends BitSetFactory[BitSet] {
   val empty: BitSet = immutable.BitSet.empty
diff --git a/src/library/scala/collection/generic/BitSetFactory.scala b/src/library/scala/collection/generic/BitSetFactory.scala
index cd26dc14b5..5679b25351 100644
--- a/src/library/scala/collection/generic/BitSetFactory.scala
+++ b/src/library/scala/collection/generic/BitSetFactory.scala
@@ -15,8 +15,17 @@ package generic
 import scala.collection._
 import mutable.{Builder, AddingBuilder}
 
-/**
- * @since 2.8
+/** @define coll collection
+ *  @define Coll Traversable
+ *  @define factoryInfo
+ *    This object provides a set of operations to create `$Coll` values.
+ *    @author Martin Odersky
+ *    @version 2.8
+ *  @define canBuildFromInfo
+ *    The standard `CanBuildFrom` instance for $Coll objects.
+ *    @see CanBuildFrom
+ *  @define bitsetCanBuildFrom
+ *    The standard `CanBuildFrom` instance for bitsets.
  */
 trait BitSetFactory[Coll <: BitSet with BitSetLike[Coll]] {
   def newBuilder: Builder[Int, Coll] = new AddingBuilder[Int, Coll](empty)
diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala
index 1b74f82781..7efa56f0a9 100644
--- a/src/library/scala/collection/mutable/ArrayBuffer.scala
+++ b/src/library/scala/collection/mutable/ArrayBuffer.scala
@@ -35,6 +35,10 @@ import generic._
  *    result class `That` from the current representation type `Repr`
  *    and the new element type `B`. This is usually the `canBuildFrom` value
  *    defined in object `ArrayBuffer`.
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(1529165946227428979L)
 class ArrayBuffer[A](override protected val initialSize: Int)
diff --git a/src/library/scala/collection/mutable/ArrayBuilder.scala b/src/library/scala/collection/mutable/ArrayBuilder.scala
index 353836b77d..0ddd089852 100644
--- a/src/library/scala/collection/mutable/ArrayBuilder.scala
+++ b/src/library/scala/collection/mutable/ArrayBuilder.scala
@@ -18,6 +18,8 @@ import scala.reflect.ClassManifest
 /** A builder class for arrays.
  *
  *  @since 2.8
+ *
+ *  @tparam T    the type of the elements for the builder.
  */
 @serializable
 abstract class ArrayBuilder[T] extends Builder[T, Array[T]]
diff --git a/src/library/scala/collection/mutable/ArrayLike.scala b/src/library/scala/collection/mutable/ArrayLike.scala
index 8a5af5211a..b3bd0fbe25 100644
--- a/src/library/scala/collection/mutable/ArrayLike.scala
+++ b/src/library/scala/collection/mutable/ArrayLike.scala
@@ -18,6 +18,9 @@ import generic._
  *
  *  @since 2.8
  *
+ *  @tparam A     type of the elements contained in the array like object.
+ *  @tparam Repr  the type of the actual collection containing the elements.
+ *
  *  @define Coll ArrayLike
  */
 trait ArrayLike[A, +Repr] extends IndexedSeqOptimized[A, Repr] { self =>
diff --git a/src/library/scala/collection/mutable/ArrayOps.scala b/src/library/scala/collection/mutable/ArrayOps.scala
index 2ea4a780f2..971709ed67 100644
--- a/src/library/scala/collection/mutable/ArrayOps.scala
+++ b/src/library/scala/collection/mutable/ArrayOps.scala
@@ -24,7 +24,13 @@ import scala.reflect.ClassManifest
  *
  *  @since 2.8
  *
+ *  @tparam T   type of the elements contained in this array.
+ *
  *  @define Coll ArrayOps
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
 
diff --git a/src/library/scala/collection/mutable/ArraySeq.scala b/src/library/scala/collection/mutable/ArraySeq.scala
index f6f958601d..c903dae55c 100644
--- a/src/library/scala/collection/mutable/ArraySeq.scala
+++ b/src/library/scala/collection/mutable/ArraySeq.scala
@@ -21,6 +21,23 @@ import generic._
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.8
+ *
+ *  @tparam A      type of the elements contained in this array sequence.
+ *  @param length  the length of the underlying array.
+ *
+ *  @define Coll ArraySeq
+ *  @define coll array sequence
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `ArraySeq[B]` because an implicit of type `CanBuildFrom[ArraySeq, B, That]`
+ *    is defined in object `ArraySeq`.
+ *  @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ *    result class `That` from the current representation type `Repr`
+ *    and the new element type `B`. This is usually the `canBuildFrom` value
+ *    defined in object `ArraySeq`.
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 class ArraySeq[A](override val length: Int)
 extends IndexedSeq[A]
@@ -49,7 +66,7 @@ extends IndexedSeq[A]
     }
   }
 
-  /** Fills the given array <code>xs</code> with at most `len` elements of
+  /** Fills the given array `xs` with at most `len` elements of
    *  this traversable starting at position `start`.
    *  Copying will stop once either the end of the current traversable is reached or
    *  `len` elements have been copied or the end of the array is reached.
@@ -64,7 +81,12 @@ extends IndexedSeq[A]
    }
 }
 
+/** $factoryInfo
+ *  @define coll array sequence
+ *  @define Coll ArraySeq
+ */
 object ArraySeq extends SeqFactory[ArraySeq] {
+  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ArraySeq[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, ArraySeq[A]] =
     new ArrayBuffer[A] mapResult { buf =>
diff --git a/src/library/scala/collection/mutable/ArrayStack.scala b/src/library/scala/collection/mutable/ArrayStack.scala
index 8f9d1bfc88..0c6dc7a0e1 100644
--- a/src/library/scala/collection/mutable/ArrayStack.scala
+++ b/src/library/scala/collection/mutable/ArrayStack.scala
@@ -28,12 +28,20 @@ private object Utils {
   }
 }
 
-/**
- * Simple stack class backed by an array. Should be significantly faster
- * than the standard mutable stack.
+/** Simple stack class backed by an array. Should be significantly faster
+ *  than the standard mutable stack.
  *
- * @author David MacIver
- * @since  2.7
+ *  @author David MacIver
+ *  @since  2.7
+ *
+ *  @tparam T    type of the elements contained in this array stack.
+ *
+ *  @define Coll ArrayStack
+ *  @define coll array stack
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @cloneable @serializable @SerialVersionUID(8565219180626620510L)
 class ArrayStack[T] private(private var table : Array[AnyRef],
@@ -47,10 +55,9 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
   /** The number of elements in the stack */
   def length = index
 
-  /**
-   * Push an element onto the stack.
+  /** Push an element onto the stack.
    *
-   * @param x The element to push
+   *  @param x The element to push
    */
   def push(x: T) {
     if (index == table.length) table = Utils.growArray(table)
@@ -58,8 +65,9 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
     index += 1
   }
 
-  /**
-   * Pop the top element off the stack.
+  /** Pop the top element off the stack.
+   *
+   *  @return the element on top of the stack
    */
   def pop: T = {
     if (index == 0) error("Stack empty")
@@ -73,68 +81,73 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
   @deprecated("use top instead")
   def peek = top
 
-  /**
-   * View the top element of the stack.
+  /** View the top element of the stack.
+   *
+   *  Does not remove the element on the top. If the stack is empty,
+   *  an exception is thrown.
+   *
+   *  @return the element on top of the stack.
    */
   def top: T = table(index - 1).asInstanceOf[T]
 
-  /**
-   * Duplicate the top element of the stack.
+  /** Duplicate the top element of the stack.
+   *
+   *  After calling this method, the stack will have an additional element at
+   *  the top equal to the element that was previously at the top.
+   *  If the stack is empty, an exception is thrown.
    */
   def dup = push(top)
 
-  /**
-   * Empties the stack.
-   */
+  /** Empties the stack. */
   def clear {
     index = 0
     table = new Array(1)
   }
 
-  /**
-   * Empties the stack, passing all elements on it in FIFO order to the
-   * provided function.
+  /** Empties the stack, passing all elements on it in LIFO order to the
+   *  provided function.
    *
-   * @param f The function to drain to.
+   *  @param f The function to drain to.
    */
   def drain(f: T => Unit) = while (!isEmpty) f(pop)
 
-  /**
-   * Pushes all the provided elements onto the stack.
+  /** Pushes all the provided elements in the traversable object onto the stack.
    *
-   * @param x The source of elements to push
+   *  @param x  The source of elements to push.
+   *  @return   A reference to this stack.
    */
   def ++=(xs: TraversableOnce[T]): this.type = { xs foreach += ; this }
 
-  /**
-   *  Alias for push.
+  /** Does the same as `push`, but returns the updated stack.
    *
-   *  @param x The element to push
+   *  @param x  The element to push.
+   *  @return   A reference to this stack.
    */
   def +=(x: T): this.type = { push(x); this }
 
-  /**
-   * Pop the top two elements off the stack, apply f to them and push the result
-   * back on to the stack.
+  /** Pop the top two elements off the stack, apply `f` to them and push the result
+   *  back on to the stack.
    *
-   * @param f The combining function
+   *  This function will throw an exception if stack contains fewer than 2 elements.
+   *
+   *  @param f   The function to apply to the top two elements.
    */
-  def combine(f: (T, T) => T) = push(f(pop, pop));
+  def combine(f: (T, T) => T): Unit = push(f(pop, pop))
 
-  /**
-   * Repeatedly combine the top elements of the stack until the stack contains only
-   * one element.
+  /** Repeatedly combine the top elements of the stack until the stack contains only
+   *  one element.
+   *
+   *  @param f   The function to apply repeatedly to topmost elements.
    */
-  def reduceWith(f: (T, T) => T) = while(size > 1) combine(f)
+  def reduceWith(f: (T, T) => T): Unit = while(size > 1) combine(f)
 
   override def size = index
 
-  /**
-   * Evaluates the expression, preserving the contents of the stack so that
-   * any changes the evaluation makes to the stack contents will be undone after
-   * it completes.
+  /** Evaluates the expression, preserving the contents of the stack so that
+   *  any changes the evaluation makes to the stack contents will be undone after
+   *  it completes.
    *
-   * @param action The action to run.
+   *  @param action The action to run.
    */
   def preserving[T](action: => T) = {
     val oldIndex = index
@@ -150,8 +163,8 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
 
   override def isEmpty: Boolean = index == 0
 
-  /**
-   * Iterates over the stack in LIFO order.
+  /** Creates and iterator over the stack in LIFO order.
+   *  @return an iterator over the elements of the stack.
    */
   def iterator: Iterator[T] = new Iterator[T] {
     var currentIndex = index
diff --git a/src/library/scala/collection/mutable/BitSet.scala b/src/library/scala/collection/mutable/BitSet.scala
index 388aa4dc43..5d0f5863ca 100644
--- a/src/library/scala/collection/mutable/BitSet.scala
+++ b/src/library/scala/collection/mutable/BitSet.scala
@@ -16,7 +16,22 @@ import generic._
 import BitSetLike.{LogWL, updateArray}
 
 /** A class for mutable bitsets.
+ *
  *  $bitsetinfo
+ *
+ *  @define Coll BitSet
+ *  @define coll bitset
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `BitSet[B]` because an implicit of type `CanBuildFrom[BitSet, B, BitSet]`
+ *    is defined in object `BitSet`.
+ *  @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ *    result class `That` from the current representation type `Repr`
+ *    and the new element type `B`. This is usually the `canBuildFrom` value
+ *    defined in object `BitSet`.
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(8483111450368547763L)
 class BitSet(protected var elems: Array[Long]) extends Set[Int]
@@ -26,6 +41,10 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
 
   override def empty = BitSet.empty
 
+  /** Creates the bitset of a certain initial size.
+   *
+   *  @param initSize    initial size of the bitset.
+   */
   def this(initSize: Int) = this(new Array[Long]((initSize + 63) >> 6 max 1))
 
   def this() = this(0)
@@ -75,7 +94,10 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
 
   /** Wraps this bitset as an immutable bitset backed by the array of bits
    *  of this bitset.
+   *
    *  @note Subsequent changes in this bitset will be reflected in the returned immutable bitset.
+   *
+   *  @return an immutable set containing all the elements of this set.
    */
   def toImmutable = immutable.BitSet.fromArray(elems)
 
@@ -86,8 +108,12 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
   }
 }
 
+/** $factoryInfo
+ *  @define coll bitset
+ *  @define Coll BitSet
+ */
 object BitSet extends BitSetFactory[BitSet] {
   def empty: BitSet = new BitSet
-  /** $canBuildFromInfo */
+  /** $bitsetCanBuildFrom */
   implicit def canBuildFrom: CanBuildFrom[BitSet, Int, BitSet] = bitsetCanBuildFrom
 }
diff --git a/src/library/scala/collection/mutable/Buffer.scala b/src/library/scala/collection/mutable/Buffer.scala
index 1c8aeb6b7a..fbc52ae322 100644
--- a/src/library/scala/collection/mutable/Buffer.scala
+++ b/src/library/scala/collection/mutable/Buffer.scala
@@ -18,12 +18,17 @@ import generic._
  *  appending, prepending, or inserting new elements. It is also
  *  possible to access and modify elements in a random access fashion
  *  via the index of the element in the current sequence.
-  *
+ *
  *  @author Matthias Zenger
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   1
-  */
+ *
+ *  @tparam A    type of the elements contained in this buffer.
+ *
+ *  @define Coll Buffer
+ *  @define coll buffer
+ */
 @cloneable
 trait Buffer[A] extends Seq[A]
                    with GenericTraversableTemplate[A, Buffer]
@@ -31,7 +36,9 @@ trait Buffer[A] extends Seq[A]
   override def companion: GenericCompanion[Buffer] = Buffer
 }
 
-/** Factory object for <code>Buffer</code> trait.
+/** $factoryInfo
+ *  @define coll buffer
+ *  @define Coll Buffer
  */
 object Buffer extends SeqFactory[Buffer] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Buffer[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/mutable/BufferProxy.scala b/src/library/scala/collection/mutable/BufferProxy.scala
index 71c2bc4ca1..983572452b 100644
--- a/src/library/scala/collection/mutable/BufferProxy.scala
+++ b/src/library/scala/collection/mutable/BufferProxy.scala
@@ -16,13 +16,18 @@ import generic._
 import script._
 
 /** This is a simple proxy class for <a href="Buffer.html"
- *  target="contentFrame"><code>scala.collection.mutable.Buffer</code></a>.
+ *  target="contentFrame">`scala.collection.mutable.Buffer`</a>.
  *  It is most useful for assembling customized set abstractions
  *  dynamically using object composition and forwarding.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 16/04/2004
  *  @since   1
+ *
+ *  @tparam A     type of the elements the buffer proxy contains.
+ *
+ *  @define Coll BufferProxy
+ *  @define coll buffer proxy
  */
 trait BufferProxy[A] extends Buffer[A] with Proxy {
 
@@ -63,10 +68,10 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
               "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 a traversable object
-   *  via its <code>foreach</code> method.
+  /** Appends a number of elements provided by a traversable object.
    *
-   *  @param iter  the traversable object.
+   *  @param xs   the traversable object.
+   *  @return     a reference to this $coll.
    */
   override def ++=(xs: TraversableOnce[A]): this.type = { self.++=(xs); this }
 
@@ -76,10 +81,9 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    */
   override def append(elems: A*) { self.++=(elems) }
 
-  /** Appends a number of elements provided by a traversable object
-   *  via its <code>foreach</code> method.
+  /** Appends a number of elements provided by a traversable object.
    *
-   *  @param iter  the traversable object.
+   *  @param xs   the traversable object.
    */
   override def appendAll(xs: TraversableOnce[A]) { self.appendAll(xs) }
 
@@ -87,6 +91,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    *  the identity of the buffer.
    *
    *  @param elem  the element to append.
+   *  @return      a reference to this $coll.
    */
   def +=:(elem: A): this.type = { self.+=:(elem); this }
 
@@ -98,26 +103,25 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    */
   override def prepend(elems: A*) { self.prependAll(elems) }
 
-  /** Prepends a number of elements provided by a traversable object
-   *  via its <code>foreach</code> method. The identity of the
-   *  buffer is returned.
+  /** Prepends a number of elements provided by a traversable object.
+   *  The identity of the buffer is returned.
    *
    *  @param xs  the traversable object.
    */
   override def prependAll(xs: TraversableOnce[A]) { self.prependAll(xs) }
 
-  /** Inserts new elements at the index <code>n</code>. Opposed to method
-   *  <code>update</code>, this method will not replace an element with a
-   *  one. Instead, it will insert the new elements at index <code>n</code>.
+  /** Inserts new elements at the index `n`. Opposed to method
+   *  `update`, this method will not replace an element with a
+   *  one. Instead, it will insert the new elements at index `n`.
    *
    *  @param n      the index where a new element will be inserted.
    *  @param elems  the new elements to insert.
    */
   override def insert(n: Int, elems: A*) { self.insertAll(n, elems) }
 
-  /** Inserts new elements at the index <code>n</code>. Opposed to method
-   *  <code>update</code>, this method will not replace an element with a
-   *  one. Instead, it will insert a new element at index <code>n</code>.
+  /** Inserts new elements at the index `n`. Opposed to method
+   *  `update`, this method will not replace an element with a
+   *  one. Instead, it will insert a new element at index `n`.
    *
    *  @param n     the index where a new element will be inserted.
    *  @param iter  the iterable object providing all elements to insert.
@@ -126,8 +130,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
 
   override def insertAll(n: Int, iter: scala.collection.Traversable[A]): Unit = self.insertAll(n, iter)
 
-  /** Replace element at index <code>n</code> with the new element
-   *  <code>newelem</code>.
+  /** Replace element at index `n` with the new element `newelem`.
    *
    *  @param n       the index of the element to replace.
    *  @param newelem the new element.
@@ -152,7 +155,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
 
   /** Return a clone of this buffer.
    *
-   *  @return a <code>Buffer</code> with the same elements.
+   *  @return a `Buffer` with the same elements.
    */
   override def clone(): Buffer[A] = new BufferProxy[A] {
     def self = BufferProxy.this.self.clone()
diff --git a/src/library/scala/collection/mutable/Builder.scala b/src/library/scala/collection/mutable/Builder.scala
index 2e6a9149bc..a930c29948 100644
--- a/src/library/scala/collection/mutable/Builder.scala
+++ b/src/library/scala/collection/mutable/Builder.scala
@@ -15,7 +15,7 @@ import generic._
 
 /** The base trait of all builders.
  *  A builder lets one construct a collection incrementally, by adding
- *  elements to the builder with += and then converting to the required
+ *  elements to the builder with `+=` and then converting to the required
  *  collection type with `result`.
  *
  *  @tparam  Elem  the type of elements that get added to the builder.