Docs. No review.

4 files changed, 85 insertions, 33 deletions

diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala
index 7dd2af80cb..1b74f82781 100644
--- a/src/library/scala/collection/mutable/ArrayBuffer.scala
+++ b/src/library/scala/collection/mutable/ArrayBuffer.scala
@@ -14,7 +14,7 @@ package mutable
 
 import generic._
 
-/** An implementation of the <code>Buffer</code> class using an array to
+/** An implementation of the `Buffer` class using an array to
  *  represent the assembled sequence internally. Append, update and random
  *  access take constant time (amortized time). Prepends and removes are
  *  linear in the buffer size.
@@ -23,6 +23,18 @@ import generic._
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since   1
+ *
+ *  @tparam A    the type of this arraybuffer's elements.
+ *
+ *  @define Coll ArrayBuffer
+ *  @define coll arraybuffer
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `ArrayBuffer[B]` because an implicit of type `CanBuildFrom[ArrayBuffer, B, That]`
+ *    is defined in object `ArrayBuffer`.
+ *  @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 `ArrayBuffer`.
  */
 @serializable @SerialVersionUID(1529165946227428979L)
 class ArrayBuffer[A](override protected val initialSize: Int)
@@ -50,9 +62,10 @@ class ArrayBuffer[A](override protected val initialSize: Int)
   }
 
   /** Appends a single element to this buffer and returns
-   *  the identity of the buffer. It takes constant time.
+   *  the identity of the buffer. It takes constant amortized time.
    *
    *  @param elem  the element to append.
+   *  @return      the updated buffer.
    */
   def +=(elem: A): this.type = {
     ensureSize(size0 + 1)
@@ -61,11 +74,10 @@ class ArrayBuffer[A](override protected val initialSize: Int)
     this
   }
 
-  /** 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.
+   *  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 = xs match {
@@ -79,7 +91,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
       super.++=(xs)
   }
 
-  /** Prepends a single element to this buffer and return
+  /** Prepends a single element to this buffer and returns
    *  the identity of the buffer. It takes time linear in
    *  the buffer size.
    *
@@ -94,22 +106,21 @@ class ArrayBuffer[A](override protected val initialSize: Int)
     this
   }
 
-  /** Prepends a number of elements provided by a traversable object
-   *  via its <code>iterator</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.
    *  @return      the updated buffer.
    */
   override def ++=:(xs: TraversableOnce[A]): this.type = { insertAll(0, xs.toTraversable); this }
 
-  /** 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 seq   the traversable object providing all elements to insert.
-   *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
+   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
    */
   def insertAll(n: Int, seq: Traversable[A]) {
     if (n < 0 || n > size0) throw new IndexOutOfBoundsException(n.toString)
@@ -124,9 +135,9 @@ class ArrayBuffer[A](override protected val initialSize: Int)
   /** Removes the element on a given index position. It takes time linear in
    *  the buffer size.
    *
-   *  @param n  the index which refers to the first element to delete.
+   *  @param n       the index which refers to the first element to delete.
    *  @param count   the number of elements to delete
-   *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
+   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
    */
   override def remove(n: Int, count: Int) {
     require(count >= 0, "removing negative number of elements")
@@ -135,10 +146,10 @@ class ArrayBuffer[A](override protected val initialSize: Int)
     reduceToSize(size0 - count)
   }
 
-  /** Removes the element on a given index position
+  /** Removes the element at a given index position.
    *
    *  @param n  the index which refers to the element to delete.
-   *  @return  The element that was formerly at position `n`
+   *  @return   the element that was formerly at position `n`.
    */
   def remove(n: Int): A = {
     val result = apply(n)
@@ -148,7 +159,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
 
   /** Return a clone of this buffer.
    *
-   *  @return an <code>ArrayBuffer</code> with the same elements.
+   *  @return an `ArrayBuffer` with the same elements.
    */
   override def clone(): ArrayBuffer[A] = new ArrayBuffer[A] ++= this
 
@@ -159,13 +170,14 @@ class ArrayBuffer[A](override protected val initialSize: Int)
   override def stringPrefix: String = "ArrayBuffer"
 }
 
-/** Factory object for <code>ArrayBuffer</code> class.
+/** Factory object for the `ArrayBuffer` class.
  *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.8
+ *  $factoryInfo
+ *  @define coll list
+ *  @define Coll List
  */
 object ArrayBuffer extends SeqFactory[ArrayBuffer] {
+  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ArrayBuffer[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, ArrayBuffer[A]] = new ArrayBuffer[A]
 }
diff --git a/src/library/scala/collection/mutable/ArrayBuilder.scala b/src/library/scala/collection/mutable/ArrayBuilder.scala
index 71f6126735..353836b77d 100644
--- a/src/library/scala/collection/mutable/ArrayBuilder.scala
+++ b/src/library/scala/collection/mutable/ArrayBuilder.scala
@@ -17,19 +17,29 @@ import scala.reflect.ClassManifest
 
 /** A builder class for arrays.
  *
- * @since 2.8
+ *  @since 2.8
  */
 @serializable
 abstract class ArrayBuilder[T] extends Builder[T, Array[T]]
 
-/**
- * @since 2.8
+/** A companion object for array builders.
+ *
+ *  @since 2.8
  */
 object ArrayBuilder {
 
+  /** Creates a new arraybuilder of type `T`.
+   *
+   *  @tparam T     type of the elements for the array builder, with a `ClassManifest` context bound.
+   *  @return       a new empty array builder.
+   */
   def make[T: ClassManifest](): ArrayBuilder[T] =
     implicitly[ClassManifest[T]].newArrayBuilder()
 
+  /** A class for array builders for arrays of reference types.
+   *
+   *  @tparam T     type of elements for the array builder, subtype of `AnyRef` with a `ClassManifest` context bound.
+   */
   class ofRef[T <: AnyRef : ClassManifest] extends ArrayBuilder[T] {
 
     private var elems: Array[T] = _
@@ -94,6 +104,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofRef"
   }
 
+  /** A class for array builders for arrays of `byte`s. */
   class ofByte extends ArrayBuilder[Byte] {
 
     private var elems: Array[Byte] = _
@@ -158,6 +169,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofByte"
   }
 
+  /** A class for array builders for arrays of `short`s. */
   class ofShort extends ArrayBuilder[Short] {
 
     private var elems: Array[Short] = _
@@ -222,6 +234,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofShort"
   }
 
+  /** A class for array builders for arrays of `char`s. */
   class ofChar extends ArrayBuilder[Char] {
 
     private var elems: Array[Char] = _
@@ -286,6 +299,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofChar"
   }
 
+  /** A class for array builders for arrays of `int`s. */
   class ofInt extends ArrayBuilder[Int] {
 
     private var elems: Array[Int] = _
@@ -350,6 +364,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofInt"
   }
 
+  /** A class for array builders for arrays of `long`s. */
   class ofLong extends ArrayBuilder[Long] {
 
     private var elems: Array[Long] = _
@@ -414,6 +429,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofLong"
   }
 
+  /** A class for array builders for arrays of `float`s. */
   class ofFloat extends ArrayBuilder[Float] {
 
     private var elems: Array[Float] = _
@@ -478,6 +494,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofFloat"
   }
 
+  /** A class for array builders for arrays of `double`s. */
   class ofDouble extends ArrayBuilder[Double] {
 
     private var elems: Array[Double] = _
@@ -542,6 +559,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofDouble"
   }
 
+  /** A class for array builders for arrays of `boolean`s. */
   class ofBoolean extends ArrayBuilder[Boolean] {
 
     private var elems: Array[Boolean] = _
@@ -606,6 +624,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofBoolean"
   }
 
+  /** A class for array builders for arrays of `Unit` type. */
   class ofUnit extends ArrayBuilder[Unit] {
 
     private var elems: Array[Unit] = _
diff --git a/src/library/scala/collection/mutable/ArrayLike.scala b/src/library/scala/collection/mutable/ArrayLike.scala
index 0b64f1255e..8a5af5211a 100644
--- a/src/library/scala/collection/mutable/ArrayLike.scala
+++ b/src/library/scala/collection/mutable/ArrayLike.scala
@@ -13,21 +13,28 @@ package scala.collection
 package mutable
 import generic._
 
-/** A subtrait of collection.IndexedSeq which represents sequences
+/** A subtrait of `collection.IndexedSeq` which represents sequences
  *  that can be mutated.
  *
  *  @since 2.8
+ *
+ *  @define Coll ArrayLike
  */
 trait ArrayLike[A, +Repr] extends IndexedSeqOptimized[A, Repr] { self =>
 
-  /** Creates a possible nested IndexedSeq which consists of all the elements
-   *  of this array. If the elements are arrays themselves, the `deep' transformation
-   *  is applied recursively to them. The stringPrefix of the IndexedSeq is
-   *  "Array", hence the IndexedSeq prints like an array with all its
+  /** Creates a possible nested `IndexedSeq` which consists of all the elements
+   *  of this array. If the elements are arrays themselves, the `deep` transformation
+   *  is applied recursively to them. The `stringPrefix` of the `IndexedSeq` is
+   *  "Array", hence the `IndexedSeq` prints like an array with all its
    *  elements shown, and the same recursively for any subarrays.
    *
-   *  Example:   Array(Array(1, 2), Array(3, 4)).deep.toString
-   *  prints:    Array(Array(1, 2), Array(3, 4))
+   *  Example:
+   *  {{{
+   *  Array(Array(1, 2), Array(3, 4)).deep.toString
+   *  }}}
+   *  prints: `Array(Array(1, 2), Array(3, 4))`
+   *
+   *  @return    An possibly nested indexed sequence of consisting of all the elements of the array.
    */
   def deep: scala.collection.IndexedSeq[Any] = new scala.collection.IndexedSeq[Any] {
     def length = self.length
diff --git a/src/library/scala/collection/mutable/ArrayOps.scala b/src/library/scala/collection/mutable/ArrayOps.scala
index 3d9d103b06..2ea4a780f2 100644
--- a/src/library/scala/collection/mutable/ArrayOps.scala
+++ b/src/library/scala/collection/mutable/ArrayOps.scala
@@ -23,6 +23,8 @@ import scala.reflect.ClassManifest
  *  will remain a `WrappedArray`.
  *
  *  @since 2.8
+ *
+ *  @define Coll ArrayOps
  */
 abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
 
@@ -75,10 +77,13 @@ abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
 }
 
 /**
+ * A companion object for `ArrayOps`.
+ *
  * @since 2.8
  */
 object ArrayOps {
 
+  /** A class of `ArrayOps` for arrays containing reference types. */
   class ofRef[T <: AnyRef](override val repr: Array[T]) extends ArrayOps[T] with ArrayLike[T, Array[T]] {
 
     override protected[this] def thisCollection: WrappedArray[T] = new WrappedArray.ofRef[T](repr)
@@ -91,6 +96,7 @@ object ArrayOps {
     def update(index: Int, elem: T) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `byte`s. */
   class ofByte(override val repr: Array[Byte]) extends ArrayOps[Byte] with ArrayLike[Byte, Array[Byte]] {
 
     override protected[this] def thisCollection: WrappedArray[Byte] = new WrappedArray.ofByte(repr)
@@ -102,6 +108,7 @@ object ArrayOps {
     def update(index: Int, elem: Byte) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `short`s. */
   class ofShort(override val repr: Array[Short]) extends ArrayOps[Short] with ArrayLike[Short, Array[Short]] {
 
     override protected[this] def thisCollection: WrappedArray[Short] = new WrappedArray.ofShort(repr)
@@ -113,6 +120,7 @@ object ArrayOps {
     def update(index: Int, elem: Short) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `char`s. */
   class ofChar(override val repr: Array[Char]) extends ArrayOps[Char] with ArrayLike[Char, Array[Char]] {
 
     override protected[this] def thisCollection: WrappedArray[Char] = new WrappedArray.ofChar(repr)
@@ -124,6 +132,7 @@ object ArrayOps {
     def update(index: Int, elem: Char) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `int`s. */
   class ofInt(override val repr: Array[Int]) extends ArrayOps[Int] with ArrayLike[Int, Array[Int]] {
 
     override protected[this] def thisCollection: WrappedArray[Int] = new WrappedArray.ofInt(repr)
@@ -135,6 +144,7 @@ object ArrayOps {
     def update(index: Int, elem: Int) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `long`s. */
   class ofLong(override val repr: Array[Long]) extends ArrayOps[Long] with ArrayLike[Long, Array[Long]] {
 
     override protected[this] def thisCollection: WrappedArray[Long] = new WrappedArray.ofLong(repr)
@@ -146,6 +156,7 @@ object ArrayOps {
     def update(index: Int, elem: Long) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `float`s. */
   class ofFloat(override val repr: Array[Float]) extends ArrayOps[Float] with ArrayLike[Float, Array[Float]] {
 
     override protected[this] def thisCollection: WrappedArray[Float] = new WrappedArray.ofFloat(repr)
@@ -157,6 +168,7 @@ object ArrayOps {
     def update(index: Int, elem: Float) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `double`s. */
   class ofDouble(override val repr: Array[Double]) extends ArrayOps[Double] with ArrayLike[Double, Array[Double]] {
 
     override protected[this] def thisCollection: WrappedArray[Double] = new WrappedArray.ofDouble(repr)
@@ -168,6 +180,7 @@ object ArrayOps {
     def update(index: Int, elem: Double) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `boolean`s. */
   class ofBoolean(override val repr: Array[Boolean]) extends ArrayOps[Boolean] with ArrayLike[Boolean, Array[Boolean]] {
 
     override protected[this] def thisCollection: WrappedArray[Boolean] = new WrappedArray.ofBoolean(repr)
@@ -179,6 +192,7 @@ object ArrayOps {
     def update(index: Int, elem: Boolean) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays of `Unit` types. */
   class ofUnit(override val repr: Array[Unit]) extends ArrayOps[Unit] with ArrayLike[Unit, Array[Unit]] {
 
     override protected[this] def thisCollection: WrappedArray[Unit] = new WrappedArray.ofUnit(repr)