Merged revisions 22722,22732,22775-22776,22779-...

Merged revisions
22722,22732,22775-22776,22779-22780,22785-22786,22825-22827,22844-22845
via svnmerge from https://lampsvn.epfl.ch/svn-repos/scala/scala/trunk

........
  r22722 | rytz | 2010-08-10 13:46:49 +0200 (Tue, 10 Aug 2010) | 1 line

  fix an msil bug (code gen of exception handlers). no review. ........
r22732 | rytz | 2010-08-11 14:32:07 +0200 (Wed, 11 Aug 2010) | 1 line

  Correct fix for see #3726. no review, discussed with martin. ........
r22775 | rytz | 2010-08-16 19:29:36 +0200 (Mon, 16 Aug 2010) | 1 line

  doc comment for scala package. (did not add comment on currentThread
because of see #3762). close #3750, no review. ........ r22776 | rytz |
2010-08-16 19:29:40 +0200 (Mon, 16 Aug 2010) | 1 line

  documentation for scala.Array. thanks for the patches! close #3751, no
review. ........ r22779 | rytz | 2010-08-16 19:35:07 +0200 (Mon, 16 Aug
2010) | 1 line

  use arraycopy instead of Array.copy in ArrayBuffer's sizeHint. close
#3766, review by extempore. ........ r22780 | rytz | 2010-08-16 20:40:54
+0200 (Mon, 16 Aug 2010) | 3 lines

  Revert ArrayBuffer's sizeHint as I had a typo anyway and it needs more
thinking. see #3766, see #3767.

  This reverts commit bf87118d701df2313a9f680e327ce066765c10d3. ........
r22785 | rytz | 2010-08-17 16:43:22 +0200 (Tue, 17 Aug 2010) | 1 line

  use arraycopy not Array.copy in Arraybuffer.sizeHint. close #3766,
#3767. no review. ........ r22786 | rytz | 2010-08-17 19:15:08 +0200
(Tue, 17 Aug 2010) | 1 line

  better fix for see #3667. not all objects are serializable, only
companions of case classes or other serializable classes. review by
polcinic. ........ r22825 | rytz | 2010-08-23 15:17:00 +0200 (Mon, 23
Aug 2010) | 1 line

  test for #3667. no review
........
  r22826 | rytz | 2010-08-23 15:17:03 +0200 (Mon, 23 Aug 2010) | 1 line

  test for see #3769. no review.
........
  r22827 | rytz | 2010-08-23 15:17:06 +0200 (Mon, 23 Aug 2010) | 1 line

  in refchecks, visit the qualifier of irrefutable filters. close #3773.
review by moors. ........ r22844 | rytz | 2010-08-26 16:35:02 +0200
(Thu, 26 Aug 2010) | 1 line

  documentation for scala.xml.pull, contribution by Dave Copeland. close
#3786, no review. ........ r22845 | rytz | 2010-08-26 16:35:05 +0200
(Thu, 26 Aug 2010) | 1 line

  documentation for scala.collection package, contribution by Dave
Copeland. close #3793, no review. ........

7 files changed, 243 insertions, 96 deletions

diff --git a/src/library/scala/Array.scala b/src/library/scala/Array.scala
index 9712990d73..8327b93d66 100644
--- a/src/library/scala/Array.scala
+++ b/src/library/scala/Array.scala
@@ -16,7 +16,7 @@ import compat.Platform.arraycopy
 import scala.reflect.ClassManifest
 import scala.runtime.ScalaRunTime.{array_apply, array_update}
 
-/** A class containing a fall back builder for arrays where the element type
+/** Contains a fallback builder for arrays when the element type
  *  does not have a class manifest. In that case a generic array is built.
  */
 class FallbackArrayBuilding {
@@ -35,7 +35,7 @@ class FallbackArrayBuilding {
     }
 }
 
-/** This object contains utility methods operating on arrays.
+/** Utility methods for operating on arrays.
  *
  *  @author Martin Odersky
  *  @version 1.0
@@ -47,6 +47,9 @@ object Array extends FallbackArrayBuilding {
       def apply() = ArrayBuilder.make[T]()(m)
     }
 
+  /**
+   * Returns a new [[scala.collection.mutable.ArrayBuilder]].
+   */
   def newBuilder[T](implicit m: ClassManifest[T]): ArrayBuilder[T] = ArrayBuilder.make[T]()(m)
 
   private def slowcopy(src : AnyRef,
@@ -65,15 +68,19 @@ object Array extends FallbackArrayBuilding {
   }
 
   /** Copy one array to another.
-   *  Equivalent to
-   *    <code>System.arraycopy(src, srcPos, dest, destPos, length)</code>,
-   *  except that this works also for polymorphic and boxed arrays.
+   *  Equivalent to Java's
+   *    `System.arraycopy(src, srcPos, dest, destPos, length)`,
+   *  except that this also works for polymorphic and boxed arrays.
+   *
+   *  Note that the passed-in `dest` array will be modified by this call.
    *
-   *  @param src     ...
-   *  @param srcPos  ...
-   *  @param dest    ...
-   *  @param destPos ...
-   *  @param length  ...
+   *  @param src the source array.
+   *  @param srcPos  starting position in the source array.
+   *  @param dest destination array.
+   *  @param destPos starting position in the destination array.
+   *  @param length the number of array elements to be copied.
+   *
+   *  @see `java.lang.System#arraycopy`
    */
   def copy(src: AnyRef, srcPos: Int, dest: AnyRef, destPos: Int, length: Int) {
     val srcClass = src.getClass
@@ -83,13 +90,13 @@ object Array extends FallbackArrayBuilding {
       slowcopy(src, srcPos, dest, destPos, length)
   }
 
-  /** Returns array of length 0 */
+  /** Returns an array of length 0 */
   def empty[T: ClassManifest]: Array[T] = new Array[T](0)
 
-  /** Create an array with given elements.
+  /** Creates an array with given elements.
    *
    *  @param xs the elements to put in the array
-   *  @return the array containing elements xs.
+   *  @return an array containing all elements from xs.
    */
   def apply[T: ClassManifest](xs: T*): Array[T] = {
     val array = new Array[T](xs.length)
@@ -98,6 +105,7 @@ object Array extends FallbackArrayBuilding {
     array
   }
 
+  /** Creates an array of `Boolean` objects */
   def apply(x: Boolean, xs: Boolean*): Array[Boolean] = {
     val array = new Array[Boolean](xs.length + 1)
     array(0) = x
@@ -106,6 +114,7 @@ object Array extends FallbackArrayBuilding {
     array
   }
 
+  /** Creates an array of `Byte` objects */
   def apply(x: Byte, xs: Byte*): Array[Byte] = {
     val array = new Array[Byte](xs.length + 1)
     array(0) = x
@@ -114,6 +123,7 @@ object Array extends FallbackArrayBuilding {
     array
   }
 
+  /** Creates an array of `Short` objects */
   def apply(x: Short, xs: Short*): Array[Short] = {
     val array = new Array[Short](xs.length + 1)
     array(0) = x
@@ -122,6 +132,7 @@ object Array extends FallbackArrayBuilding {
     array
   }
 
+  /** Creates an array of `Char` objects */
   def apply(x: Char, xs: Char*): Array[Char] = {
     val array = new Array[Char](xs.length + 1)
     array(0) = x
@@ -130,6 +141,7 @@ object Array extends FallbackArrayBuilding {
     array
   }
 
+  /** Creates an array of `Int` objects */
   def apply(x: Int, xs: Int*): Array[Int] = {
     val array = new Array[Int](xs.length + 1)
     array(0) = x
@@ -138,6 +150,7 @@ object Array extends FallbackArrayBuilding {
     array
   }
 
+  /** Creates an array of `Long` objects */
   def apply(x: Long, xs: Long*): Array[Long] = {
     val array = new Array[Long](xs.length + 1)
     array(0) = x
@@ -146,6 +159,7 @@ object Array extends FallbackArrayBuilding {
     array
   }
 
+  /** Creates an array of `Float` objects */
   def apply(x: Float, xs: Float*): Array[Float] = {
     val array = new Array[Float](xs.length + 1)
     array(0) = x
@@ -154,6 +168,7 @@ object Array extends FallbackArrayBuilding {
     array
   }
 
+  /** Creates an array of `Double` objects */
   def apply(x: Double, xs: Double*): Array[Double] = {
     val array = new Array[Double](xs.length + 1)
     array(0) = x
@@ -162,6 +177,7 @@ object Array extends FallbackArrayBuilding {
     array
   }
 
+  /** Creates an array of `Unit` objects */
   def apply(x: Unit, xs: Unit*): Array[Unit] = {
     val array = new Array[Unit](xs.length + 1)
     array(0) = x
@@ -170,26 +186,30 @@ object Array extends FallbackArrayBuilding {
     array
   }
 
-  /** Create array with given dimensions */
+  /** Creates array with given dimensions */
   def ofDim[T: ClassManifest](n1: Int): Array[T] =
     new Array[T](n1)
+  /** Creates a 2-dimensional array */
   def ofDim[T: ClassManifest](n1: Int, n2: Int): Array[Array[T]] = {
     val arr: Array[Array[T]] = (new Array[Array[T]](n1): Array[Array[T]])
     for (i <- 0 until n1) arr(i) = new Array[T](n2)
     arr
     // tabulate(n1)(_ => ofDim[T](n2))
   }
+  /** Creates a 3-dimensional array */
   def ofDim[T: ClassManifest](n1: Int, n2: Int, n3: Int): Array[Array[Array[T]]] =
     tabulate(n1)(_ => ofDim[T](n2, n3))
+  /** Creates a 4-dimensional array */
   def ofDim[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int): Array[Array[Array[Array[T]]]] =
     tabulate(n1)(_ => ofDim[T](n2, n3, n4))
+  /** Creates a 5-dimensional array */
   def ofDim[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int): Array[Array[Array[Array[Array[T]]]]] =
     tabulate(n1)(_ => ofDim[T](n2, n3, n4, n5))
 
-  /** Concatenate all argument sequences into a single array.
+  /** Concatenates all arrays into a single array.
    *
-   *  @param xs the given argument sequences
-   *  @return   the array created from the concatenated arguments
+   *  @param xss the given arrays
+   *  @return   the array created from concatenating `xss`
    */
   def concat[T: ClassManifest](xss: Array[T]*): Array[T] = {
     val b = newBuilder[T]
@@ -198,11 +218,19 @@ object Array extends FallbackArrayBuilding {
     b.result
   }
 
-  /** An array that contains the results of some element computation a number
+  /** Returns an array that contains the results of some element computation a number
    *  of times.
    *
-   *  @param   n  the number of elements returned
+   *  Note that this means that `elem` is computed a total of n times:
+   *  {{{
+   * scala> Array.fill(3){ java.lang.Math.random }
+   * res3: Array[Double] = Array(0.365461167592537, 1.550395944913685E-4, 0.7907242137333306)
+   *  }}}
+   *
+   *  @param   n  the number of elements desired
    *  @param   elem the element computation
+   *  @return an Array of size n, where each element contains the result of computing
+   *  `elem`.
    */
   def fill[T: ClassManifest](n: Int)(elem: => T): Array[T] = {
     val b = newBuilder[T]
@@ -215,7 +243,7 @@ object Array extends FallbackArrayBuilding {
     b.result
   }
 
-  /** A two-dimensional array that contains the results of some element
+  /** Returns a two-dimensional array that contains the results of some element
    *  computation a number of times.
    *
    *  @param   n1  the number of elements in the 1st dimension
@@ -225,7 +253,7 @@ object Array extends FallbackArrayBuilding {
   def fill[T: ClassManifest](n1: Int, n2: Int)(elem: => T): Array[Array[T]] =
     tabulate(n1)(_ => fill(n2)(elem))
 
-  /** A three-dimensional array that contains the results of some element
+  /** Returns a three-dimensional array that contains the results of some element
    *  computation a number of times.
    *
    *  @param   n1  the number of elements in the 1st dimension
@@ -236,7 +264,7 @@ object Array extends FallbackArrayBuilding {
   def fill[T: ClassManifest](n1: Int, n2: Int, n3: Int)(elem: => T): Array[Array[Array[T]]] =
     tabulate(n1)(_ => fill(n2, n3)(elem))
 
-  /** A four-dimensional array that contains the results of some element
+  /** Returns a four-dimensional array that contains the results of some element
    *  computation a number of times.
    *
    *  @param   n1  the number of elements in the 1st dimension
@@ -248,7 +276,7 @@ object Array extends FallbackArrayBuilding {
   def fill[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int)(elem: => T): Array[Array[Array[Array[T]]]] =
     tabulate(n1)(_ => fill(n2, n3, n4)(elem))
 
-  /** A five-dimensional array that contains the results of some element
+  /** Returns a five-dimensional array that contains the results of some element
    *  computation a number of times.
    *
    *  @param   n1  the number of elements in the 1st dimension
@@ -261,12 +289,12 @@ object Array extends FallbackArrayBuilding {
   def fill[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int)(elem: => T): Array[Array[Array[Array[Array[T]]]]] =
     tabulate(n1)(_ => fill(n2, n3, n4, n5)(elem))
 
-  /** An array containing values of a given function over a range of integer
+  /** Returns an array containing values of a given function over a range of integer
    *  values starting from 0.
    *
-   *  @param  n   The number of elements in the traversable
+   *  @param  n   The number of elements in the array
    *  @param  f   The function computing element values
-   *  @return A traversable consisting of elements `f(0), ..., f(n -1)`
+   *  @return A traversable consisting of elements `f(0),f(1), ..., f(n - 1)`
    */
   def tabulate[T: ClassManifest](n: Int)(f: Int => T): Array[T] = {
     val b = newBuilder[T]
@@ -279,7 +307,7 @@ object Array extends FallbackArrayBuilding {
     b.result
   }
 
-  /** A two-dimensional array containing values of a given function over
+  /** Returns a two-dimensional array containing values of a given function over
    *  ranges of integer values starting from 0.
    *
    *  @param   n1  the number of elements in the 1st dimension
@@ -289,7 +317,7 @@ object Array extends FallbackArrayBuilding {
   def tabulate[T: ClassManifest](n1: Int, n2: Int)(f: (Int, Int) => T): Array[Array[T]] =
     tabulate(n1)(i1 => tabulate(n2)(f(i1, _)))
 
-  /** A three-dimensional array containing values of a given function over
+  /** Returns a three-dimensional array containing values of a given function over
    *  ranges of integer values starting from 0.
    *
    *  @param   n1  the number of elements in the 1st dimension
@@ -300,7 +328,7 @@ object Array extends FallbackArrayBuilding {
   def tabulate[T: ClassManifest](n1: Int, n2: Int, n3: Int)(f: (Int, Int, Int) => T): Array[Array[Array[T]]] =
     tabulate(n1)(i1 => tabulate(n2, n3)(f(i1, _, _)))
 
-  /** A four-dimensional array containing values of a given function over
+  /** Returns a four-dimensional array containing values of a given function over
    *  ranges of integer values starting from 0.
    *
    *  @param   n1  the number of elements in the 1st dimension
@@ -312,7 +340,7 @@ object Array extends FallbackArrayBuilding {
   def tabulate[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int)(f: (Int, Int, Int, Int) => T): Array[Array[Array[Array[T]]]] =
     tabulate(n1)(i1 => tabulate(n2, n3, n4)(f(i1, _, _, _)))
 
-  /** A five-dimensional array containing values of a given function over
+  /** Returns a five-dimensional array containing values of a given function over
    *  ranges of integer values starting from 0.
    *
    *  @param   n1  the number of elements in the 1st dimension
@@ -325,20 +353,20 @@ object Array extends FallbackArrayBuilding {
   def tabulate[T: ClassManifest](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int)(f: (Int, Int, Int, Int, Int) => T): Array[Array[Array[Array[Array[T]]]]] =
     tabulate(n1)(i1 => tabulate(n2, n3, n4, n5)(f(i1, _, _, _, _)))
 
-  /** An array containing a sequence of increasing integers in a range.
+  /** Returns an array containing a sequence of increasing integers in a range.
    *
    *  @param from the start value of the array
-   *  @param end the end value of the array (the first value NOT returned)
+   *  @param end the end value of the array, exclusive (in other words, this is the first value '''not''' returned)
    *  @return  the array with values in range `start, start + 1, ..., end - 1`
-   *  up to, but exclusding, `end`.
+   *  up to, but excluding, `end`.
    */
   def range(start: Int, end: Int): Array[Int] = range(start, end, 1)
 
-  /** An array containing equally spaced values in some integer interval.
+  /** Returns an array containing equally spaced values in some integer interval.
    *
    *  @param start the start value of the array
-   *  @param end   the end value of the array (the first value NOT returned)
-   *  @param step  the increment value of the array (must be positive or negative)
+   *  @param end   the end value of the array, exclusive (in other words, this is the first value '''not''' returned)
+   *  @param step  the increment value of the array (may not be zero)
    *  @return      the array with values in `start, start + step, ...` up to, but excluding `end`
    */
   def range(start: Int, end: Int, step: Int): Array[Int] = {
@@ -354,11 +382,11 @@ object Array extends FallbackArrayBuilding {
     b.result
   }
 
-  /** An array containing repeated applications of a function to a start value.
+  /** Returns an array containing repeated applications of a function to a start value.
    *
    *  @param start the start value of the array
    *  @param len   the number of elements returned by the array
-   *  @param f     the function that's repeatedly applied
+   *  @param f     the function that is repeatedly applied
    *  @return      the array returning `len` values in the sequence `start, f(start), f(f(start)), ...`
    */
   def iterate[T: ClassManifest](start: T, len: Int)(f: T => T): Array[T] = {
@@ -374,17 +402,17 @@ object Array extends FallbackArrayBuilding {
     b.result
   }
 
-  /** This method is called in a pattern match { case Seq(...) => }.
+  /** Called in a pattern match like `{ case Array(x,y,z) => println('3 elements')}`.
    *
    *  @param x the selector value
-   *  @return  sequence wrapped in an option, if this is a Seq, otherwise none
+   *  @return  sequence wrapped in a [[scala.Some]], if x is a Seq, otherwise `None`
    */
   def unapplySeq[T](x: Array[T]): Option[IndexedSeq[T]] =
     if (x == null) None else Some(x.toIndexedSeq)
     // !!! the null check should to be necessary, but without it 2241 fails. Seems to be a bug
     // in pattern matcher.
 
-  /** Create an array containing several copies of an element.
+  /** Creates an array containing several copies of an element.
    *
    *  @param n    the length of the resulting array
    *  @param elem the element composing the resulting array
@@ -401,8 +429,8 @@ object Array extends FallbackArrayBuilding {
     a
   }
 
-  /** Create an array containing the values of a given function <code>f</code>
-   *  over given range <code>[0..n)</code>
+  /** Creates an array containing the values of a given function `f`
+   *  over given range `[0..n)`
    */
   @deprecated("use `Array.tabulate' instead")
   def fromFunction[T: ClassManifest](f: Int => T)(n: Int): Array[T] = {
@@ -415,37 +443,37 @@ object Array extends FallbackArrayBuilding {
     a
   }
 
-  /** Create an array containing the values of a given function <code>f</code>
-   *  over given range <code>[0..n1, 0..n2)</code>
+  /** Creates an array containing the values of a given function `f`
+   *  over given range `[0..n1, 0..n2)`
    */
   @deprecated("use `Array.tabulate' instead")
   def fromFunction[T: ClassManifest](f: (Int, Int) => T)(n1: Int, n2: Int): Array[Array[T]] =
     fromFunction(i => fromFunction(f(i, _))(n2))(n1)
 
-  /** Create an array containing the values of a given function <code>f</code>
-   *  over given range <code>[0..n1, 0..n2, 0..n3)</code>
+  /** Creates an array containing the values of a given function `f`
+   *  over given range `[0..n1, 0..n2, 0..n3)`
    */
   @deprecated("use `Array.tabulate' instead")
   def fromFunction[T: ClassManifest](f: (Int, Int, Int) => T)(n1: Int, n2: Int, n3: Int): Array[Array[Array[T]]] =
     fromFunction(i => fromFunction(f(i, _, _))(n2, n3))(n1)
 
-  /** Create an array containing the values of a given function <code>f</code>
-   *  over given range <code>[0..n1, 0..n2, 0..n3, 0..n4)</code>
+  /** Creates an array containing the values of a given function `f`
+   *  over given range `[0..n1, 0..n2, 0..n3, 0..n4)`
    */
   @deprecated("use `Array.tabulate' instead")
   def fromFunction[T: ClassManifest](f: (Int, Int, Int, Int) => T)(n1: Int, n2: Int, n3: Int, n4: Int): Array[Array[Array[Array[T]]]] =
     fromFunction(i => fromFunction(f(i, _, _, _))(n2, n3, n4))(n1)
 
-  /** Create an array containing the values of a given function <code>f</code>
-   *  over given range <code>[0..n1, 0..n2, 0..n3, 0..n4, 0..n5)</code>
+  /** Creates an array containing the values of a given function `f`
+   *  over given range `[0..n1, 0..n2, 0..n3, 0..n4, 0..n5)`
    */
   @deprecated("use `Array.tabulate' instead")
   def fromFunction[T: ClassManifest](f: (Int, Int, Int, Int, Int) => T)(n1: Int, n2: Int, n3: Int, n4: Int, n5: Int): Array[Array[Array[Array[Array[T]]]]] =
     fromFunction(i => fromFunction(f(i, _, _, _, _))(n2, n3, n4, n5))(n1)
 }
 
-/** This class represents polymorphic arrays. <code>Array[T]</code> is Scala's representation
- *  for Java's <code>T[]</code>.
+/** Represents polymorphic arrays. `Array[T]` is Scala's representation
+ *  for Java's `T[]`.
  *
  *  @author Martin Odersky
  *  @version 1.0
@@ -513,17 +541,17 @@ final class Array[T](_length: Int) {
 
   /** The element at given index.
    *  <p>
-   *    Indices start a <code>0</code>; <code>xs.apply(0)</code> is the first
-   *    element of array <code>xs</code>.
+   *    Indices start a `0`; `xs.apply(0)` is the first
+   *    element of array `xs`.
    *  </p>
    *  <p>
-   *    Note the indexing syntax <code>xs(i)</code> is a shorthand for
-   *    <code>xs.apply(i)</code>.
+   *    Note the indexing syntax `xs(i)` is a shorthand for
+   *    `xs.apply(i)`.
    *  </p>
    *
    *  @param i   the index
-   *  @throws ArrayIndexOutOfBoundsException if <code>i < 0</code> or
-   *          <code>length <= i</code>
+   *  @throws ArrayIndexOutOfBoundsException if `i < 0` or
+   *          `length <= i`
    */
   def apply(i: Int): T = throw new Error()
 
@@ -531,18 +559,18 @@ final class Array[T](_length: Int) {
    *    Update the element at given index.
    *  </p>
    *  <p>
-   *    Indices start a <code>0</code>; <code>xs.apply(0)</code> is the first
-   *    element of array <code>xs</code>.
+   *    Indices start a `0`; `xs.apply(0)` is the first
+   *    element of array `xs`.
    *  </p>
    *  <p>
-   *    Note the indexing syntax <code>xs(i) = x</code> is a shorthand
-   *    for <code>xs.update(i, x)</code>.
+   *    Note the indexing syntax `xs(i) = x` is a shorthand
+   *    for `xs.update(i, x)`.
    *  </p>
    *
    *  @param i   the index
-   *  @param x   the value to be written at index <code>i</code>
-   *  @throws ArrayIndexOutOfBoundsException if <code>i < 0</code> or
-   *          <code>length <= i</code>
+   *  @param x   the value to be written at index `i`
+   *  @throws ArrayIndexOutOfBoundsException if `i < 0` or
+   *          `length <= i`
    */
   def update(i: Int, x: T) { throw new Error() }
 
diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala
index 6412a21531..e9955b5563 100644
--- a/src/library/scala/collection/mutable/ArrayBuffer.scala
+++ b/src/library/scala/collection/mutable/ArrayBuffer.scala
@@ -59,7 +59,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
   override def sizeHint(len: Int) {
     if (len > size && len >= 1) {
       val newarray = new Array[AnyRef](len)
-      Array.copy(array, 0, newarray, 0, size0)
+      compat.Platform.arraycopy(array, 0, newarray, 0, size0)
       array = newarray
     }
   }
diff --git a/src/library/scala/collection/package.scala b/src/library/scala/collection/package.scala
index bcd2fb5d38..c0e3c14647 100644
--- a/src/library/scala/collection/package.scala
+++ b/src/library/scala/collection/package.scala
@@ -1,5 +1,72 @@
 package scala
 
+/**
+ * Contains the base traits and objects needed to use and extend Scala's collection library.
+ *
+ * == Guide ==
+ *
+ * A detailed guide for the collections library is avaialble
+ * at [[http://lampwww.epfl.ch/~odersky/whatsnew/collections-api/collections.html]].
+ *
+ * == Using Collections ==
+ *
+ * It is convienient to treat all collections as either
+ * a [[scala.collection.Traversable]] or [[scala.collection.Iterable]], as
+ * these traits define the vast majority of operations
+ * on a collection.
+ *
+ * Collections can, of course, be treated as specifically as needed, and
+ * the library is designed to ensure that
+ * the methods that transform collections will return a collection of the same
+ * type: {{{
+ * scala> val array = Array(1,2,3,4,5,6)
+ * array: Array[Int] = Array(1, 2, 3, 4, 5, 6)
+ *
+ * scala> array map { _.toString }
+ * res0: Array[java.lang.String] = Array(1, 2, 3, 4, 5, 6)
+ *
+ * scala> val list = List(1,2,3,4,5,6)
+ * list: List[Int] = List(1, 2, 3, 4, 5, 6)
+ *
+ * scala> list map { _.toString }
+ * res1: List[java.lang.String] = List(1, 2, 3, 4, 5, 6)
+ *
+ * }}}
+ *
+ * == Creating Collections ==
+ *
+ * The most common way to create a collection is to use the companion objects as factories.
+ * Of these, the three most common
+ * are [[scala.collection.immutable.Seq]], [[scala.collection.immutable.Set]], and [[scala.collection.immutable.Map]].  Their
+ * companion objects are all available
+ * as type aliases the either the [[scala]] package or in `scala.Predef`, and can be used
+ * like so:
+ * {{{
+ * scala> val seq = Seq(1,2,3,4,1)
+ * seq: Seq[Int] = List(1, 2, 3, 4, 1)
+ *
+ * scala> val set = Set(1,2,3,4,1)
+ * set: scala.collection.immutable.Set[Int] = Set(1, 2, 3, 4)
+ *
+ * scala> val map = Map(1 -> "one",2 -> "two", 3 -> "three",2 -> "too")
+ * map: scala.collection.immutable.Map[Int,java.lang.String] = Map((1,one), (2,too), (3,three))
+ * }}}
+ *
+ * It is also typical to use the [[scala.collection.immutable]] collections over those
+ * in [[scala.collection.mutable]]; The types aliased in the [[scala]] package and
+ * the `scala.Predef` object are the immutable versions.
+ *
+ * Also note that the collections library was carefully designed to include several implementations of
+ * each of the three basic collection types. These implementations have specific performance
+ * characteristics which are described
+ * in [[http://lampwww.epfl.ch/~odersky/whatsnew/collections-api/collections.html the guide]].
+ *
+ * === Converting between Java Collections ===
+ *
+ * The `JavaConversions` object provides implicit defs that will allow mostly seamless integration
+ * between Java Collections-based APIs and the Scala collections library.
+ *
+ */
 package object collection {
   import scala.collection.generic.CanBuildFrom // can't refer to CanBuild here
 
@@ -9,4 +76,4 @@ package object collection {
     new CanBuildFrom[From, T, To] { // TODO: could we just return b instead?
       def apply(from: From) = b.apply() ; def apply() = b.apply()
     }
-}
\ No newline at end of file
+}
diff --git a/src/library/scala/package.scala b/src/library/scala/package.scala
index 50eccc8ec2..9531572321 100644
--- a/src/library/scala/package.scala
+++ b/src/library/scala/package.scala
@@ -8,6 +8,9 @@
 
 
 
+/**
+ * Core Scala types. They are always available without an explicit import.
+ */
 package object scala {
   type Throwable = java.lang.Throwable
   type Exception = java.lang.Exception
diff --git a/src/library/scala/xml/pull/XMLEvent.scala b/src/library/scala/xml/pull/XMLEvent.scala
index 3de618e3a7..255bf3b8a8 100644
--- a/src/library/scala/xml/pull/XMLEvent.scala
+++ b/src/library/scala/xml/pull/XMLEvent.scala
@@ -11,27 +11,49 @@
 package scala.xml
 package pull
 
-/** This class represents an XML event for pull parsing.
- *  Pull parsing means that during the traversal of the XML
- *  tree we are parsing, each "event" is returned to the caller
- *  and the traversal is suspended.
+/** An XML event for pull parsing.  All events received during
+ * parsing will be one of the subclasses of this trait.
  */
 trait XMLEvent
 
-/** An element is encountered the first time */
+/**
+ * An Element's start tag was encountered.
+ * @param pre prefix, if any, on the element.  This is the `xs` in `<xs:string>foo</xs:string>`.
+ * @param label the name of the element, not including the prefix
+ * @param attrs any attributes on the element
+ */
 case class EvElemStart(pre: String, label: String, attrs: MetaData, scope: NamespaceBinding) extends XMLEvent
 
-/** An element is encountered the last time */
+/**
+ * An Element's end tag was encountered.
+ * @param pre prefix, if any, on the element.  This is the `xs` in `<xs:string>foo</xs:string>`.
+ * @param label the name of the element, not including the prefix
+ */
 case class EvElemEnd(pre: String, label: String) extends XMLEvent
 
-/** A text node is encountered */
+/**
+ * A text node was encountered.
+ * @param text the text that was found
+ */
 case class EvText(text: String) extends XMLEvent
 
-/** An entity reference is encountered */
+/** An entity reference was encountered.
+ * @param the name of the entity, e.g. `gt` when encountering the entity `&gt;`
+ */
 case class EvEntityRef(entity: String) extends XMLEvent
 
-/** A processing instruction is encountered */
+/**
+ * A processing instruction was encountered.
+ * @param target the "PITarget" of the processing instruction.  For the instruction `<?foo bar="baz"?>`, the target would
+ * be `foo`
+ * @param text the remainder of the instruction.  For the instruction `<?foo bar="baz"?>`, the text would
+ * be `bar="baz"`
+ * @see [[http://www.w3.org/TR/REC-xml/#sec-pi]]
+ */
 case class EvProcInstr(target: String, text: String) extends XMLEvent
 
-/** A comment is encountered */
+/**
+ * A comment was encountered
+ * @param text the text of the comment
+ */
 case class EvComment(text: String) extends XMLEvent
diff --git a/src/library/scala/xml/pull/XMLEventReader.scala b/src/library/scala/xml/pull/XMLEventReader.scala
index 90c19f9c0b..fa428a440f 100644
--- a/src/library/scala/xml/pull/XMLEventReader.scala
+++ b/src/library/scala/xml/pull/XMLEventReader.scala
@@ -16,28 +16,14 @@ import java.nio.channels.ClosedChannelException
 import scala.io.Source
 import scala.xml.parsing.{ ExternalSources, MarkupHandler, MarkupParser }
 
-/** <p>
- *   A pull parser that offers to view an XML document as a series of events.
- *   Example usage:
- *  </p><pre>
- *  <b>import</b> scala.xml.pull._
- *  <b>import</b> scala.io.Source
- *
- *  <b>object</b> reader {
- *    <b>val</b> src = Source.fromString("<hello><world/></hello>")
- *    <b>val</b> er = new XMLEventReader(src)
- *
- *    <b>def</b> main(args: Array[String]) {
- *      while (er.hasNext)
- *        Console.println(er.next)
- *    }
- *  }
- *  </pre>
+/**
+ * Main entry point into creating an event-based XML parser.  Treating this
+ * as a [[scala.collection.Iterator]] will provide access to the generated events.
+ * @param src A [[scala.io.Source]] for XML data to parse
  *
  *  @author Burak Emir
  *  @author Paul Phillips
  */
-
 class XMLEventReader(src: Source) extends ProducerConsumerIterator[XMLEvent]
 {
   // We implement a pull parser as an iterator, but since we may be operating on
diff --git a/src/library/scala/xml/pull/package.scala b/src/library/scala/xml/pull/package.scala
new file mode 100644
index 0000000000..3742c55513
--- /dev/null
+++ b/src/library/scala/xml/pull/package.scala
@@ -0,0 +1,41 @@
+package scala.xml
+
+/**
+ * Classes needed to view an XML document as a series of events.  The document
+ * is parsed by an [[scala.xml.pull.XMLEventReader]] instance.  You can treat it as
+ * an [[scala.collection.Iterator]] to retrieve the events, which are all
+ * subclasses of [[scala.xml.pull.XMLEvent]].
+ *
+ * {{{
+ * scala> val source = Source.fromString("""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+ * <?instruction custom value="customvalue"?>
+ * <!DOCTYPE foo [
+ *   <!ENTITY bar "BAR">
+ * ]><foo>Hello<!-- this is a comment --><bar>&bar;</bar><bar>&gt;</bar></foo>""")
+ *
+ * source: scala.io.Source = non-empty iterator
+ *
+ * scala> val reader = new XMLEventReader(source)
+ * reader: scala.xml.pull.XMLEventReader = non-empty iterator
+ *
+ * scala> reader.foreach{ println(_) }
+ * EvProcInstr(instruction,custom value="customvalue")
+ * EvText(
+ * )
+ * EvElemStart(null,foo,,)
+ * EvText(Hello)
+ * EvComment( this is a comment )
+ * EvElemStart(null,bar,,)
+ * EvText(BAR)
+ * EvElemEnd(null,bar)
+ * EvElemStart(null,bar,,)
+ * EvEntityRef(gt)
+ * EvElemEnd(null,bar)
+ * EvElemEnd(null,foo)
+ * EvText(
+ *
+ * )
+ *
+ * }}}
+ */
+package object pull