Fix and add comments

Also, add `empty` method.

Author: odersky

library/src-bootstrapped/scala/IArray.scala

@@ -1,22 +1,37 @@
 package scala
 import reflect.ClassTag
 
-/** It would be nice it IArray could be covariant, but unfortunately that's not
- * possible. The problem is the preculiar behavior of `Array[Any]`.
- * `Array[Any]` erases to `Object[]`. So, `IArray[Any]` also erases to `Object[]`.
- * But this means `IArray[Int]`, which erases to `Int[]`, cannot be a subtype of
- * `IArray[Any]`.
+/** An immutable array. An `IArray[T]` has the same representation as an `Array[T]`,
+ * but it cannot be updated. Unlike regular arrays, immutable arrays are covariant.
  */
 opaque type IArray[+T] = Array[_ <: T]
 
 object IArray {
 
+ /** Defines extension methods for immutable arrays */
  implied arrayOps {
+
+ /** The selection operatiom on an immutable array.
+ *
+ * @param arr the immutable array
+ * @param n the index of the element to select
+ * @return the element of the array at the given index
+ */
  inline def (arr: IArray[T]) apply[T] (n: Int): T = arr.asInstanceOf[Array[T]].apply(n)
+
+ /** The number of elements in an immutable array
+ * @param arr the immutable array
+ */
  inline def (arr: IArray[T]) length[T] : Int = arr.asInstanceOf[Array[T]].length
  }
- def apply[T: ClassTag](xs: T*): IArray[T] = Array(xs: _*)
 
+ /** An immutable array of length 0.
+ */
+ def empty[T: ClassTag]: IArray[T] = new Array[T](0)
+
+ /** An immutable array with given elements.
+ */
+ def apply[T: ClassTag](xs: T*): IArray[T] = Array(xs: _*)
  def apply(x: Boolean, xs: Boolean*): IArray[Boolean] = Array(x, xs: _*)
  def apply(x: Byte, xs: Byte*): IArray[Byte] = Array(x, xs: _*)
  def apply(x: Short, xs: Short*): IArray[Short] = Array(x, xs: _*)
@@ -27,34 +42,155 @@ object IArray {
  def apply(x: Double, xs: Double*): IArray[Double] = Array(x, xs: _*)
  def apply(x: Unit, xs: Unit*): IArray[Unit] = Array(x, xs: _*)
 
+ /** Concatenates all arrays into a single immutable array.
+ *
+ * @param xss the given immutable arrays
+ * @return the array created from concatenating `xss`
+ */
  def concat[T: ClassTag](xss: IArray[T]*): IArray[T] = Array.concat[T](xss.asInstanceOf[Seq[Array[T]]]: _*)
 
+ /** Returns an immutable array that contains the results of some element computation a number
+ * of times. Each element is determined by a separate computation.
+ *
+ * @param n the number of elements in the array
+ * @param elem the element computation
+ */
  def fill[T: ClassTag](n: Int)(elem: => T): IArray[T] =
  Array.fill(n)(elem)
+
+ /** Returns a two-dimensional immutable array that contains the results of some element computation a number
+ * of times. Each element is determined by a separate computation.
+ *
+ * @param n1 the number of elements in the 1st dimension
+ * @param n2 the number of elements in the 2nd dimension
+ * @param elem the element computation
+ */
  def fill[T: ClassTag](n1: Int, n2: Int)(elem: => T): IArray[IArray[T]] =
  Array.fill(n1, n2)(elem)
+
+ /** Returns a three-dimensional immutable array that contains the results of some element computation a number
+ * of times. Each element is determined by a separate computation.
+ *
+ * @param n1 the number of elements in the 1st dimension
+ * @param n2 the number of elements in the 2nd dimension
+ * @param n3 the number of elements in the 3nd dimension
+ * @param elem the element computation
+ */
  def fill[T: ClassTag](n1: Int, n2: Int, n3: Int)(elem: => T): IArray[IArray[IArray[T]]] =
  Array.fill(n1, n2, n3)(elem)
+
+ /** Returns a four-dimensional immutable array that contains the results of some element computation a number
+ * of times. Each element is determined by a separate computation.
+ *
+ * @param n1 the number of elements in the 1st dimension
+ * @param n2 the number of elements in the 2nd dimension
+ * @param n3 the number of elements in the 3nd dimension
+ * @param n4 the number of elements in the 4th dimension
+ * @param elem the element computation
+ */
  def fill[T: ClassTag](n1: Int, n2: Int, n3: Int, n4: Int)(elem: => T): IArray[IArray[IArray[IArray[T]]]] =
  Array.fill(n1, n2, n3, n4)(elem)
+
+ /** Returns a five-dimensional immutable array that contains the results of some element computation a number
+ * of times. Each element is determined by a separate computation.
+ *
+ * @param n1 the number of elements in the 1st dimension
+ * @param n2 the number of elements in the 2nd dimension
+ * @param n3 the number of elements in the 3nd dimension
+ * @param n4 the number of elements in the 4th dimension
+ * @param n5 the number of elements in the 5th dimension
+ * @param elem the element computation
+ */
  def fill[T: ClassTag](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int)(elem: => T): IArray[IArray[IArray[IArray[IArray[T]]]]] =
  Array.fill(n1, n2, n3, n4, n5)(elem)
 
+ /** Returns an immutable array containing values of a given function over a range of integer
+ * values starting from 0.
+ *
+ * @param n The number of elements in the array
+ * @param f The function computing element values
+ */
  def tabulate[T: ClassTag](n: Int)(f: Int => T): IArray[T] =
  Array.tabulate(n)(f)
+
+ /** Returns a two-dimensional immutable 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
+ * @param n2 the number of elements in the 2nd dimension
+ * @param f The function computing element values
+ */
  def tabulate[T: ClassTag](n1: Int, n2: Int)(f: (Int, Int) => T): IArray[IArray[T]] =
  Array.tabulate(n1, n2)(f)
+
+ /** Returns a three-dimensional immutable 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
+ * @param n2 the number of elements in the 2nd dimension
+ * @param n3 the number of elements in the 3rd dimension
+ * @param f The function computing element values
+ */
  def tabulate[T: ClassTag](n1: Int, n2: Int, n3: Int)(f: (Int, Int, Int) => T): IArray[IArray[IArray[T]]] =
  Array.tabulate(n1, n2, n3)(f)
+
+ /** Returns a four-dimensional immutable 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
+ * @param n2 the number of elements in the 2nd dimension
+ * @param n3 the number of elements in the 3rd dimension
+ * @param n4 the number of elements in the 4th dimension
+ * @param f The function computing element values
+ */
  def tabulate[T: ClassTag](n1: Int, n2: Int, n3: Int, n4: Int)(f: (Int, Int, Int, Int) => T): IArray[IArray[IArray[IArray[T]]]] =
  Array.tabulate(n1, n2, n3, n4)(f)
+
+ /** Returns a five-dimensional immutable 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
+ * @param n2 the number of elements in the 2nd dimension
+ * @param n3 the number of elements in the 3rd dimension
+ * @param n4 the number of elements in the 4th dimension
+ * @param n5 the number of elements in the 5th dimension
+ * @param f The function computing element values
+ */
  def tabulate[T: ClassTag](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int)(f: (Int, Int, Int, Int, Int) => T): IArray[IArray[IArray[IArray[IArray[T]]]]] =
  Array.tabulate(n1, n2, n3, n4, n5)(f)
 
+ /** Returns an immutable array containing a sequence of increasing integers in a range.
+ *
+ * @param start the start value of the array
+ * @param end the end value of the array, exclusive (in other words, this is the first value '''not''' returned)
+ * @return the immutable array with values in range `start, start + 1, ..., end - 1`
+ * up to, but excluding, `end`.
+ */
  def range(start: Int, end: Int): IArray[Int] = Array.range(start, end)
+
+ /** Returns an immutable 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, 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 immutable array with values in `start, start + step, ...` up to, but excluding `end`
+ */
  def range(start: Int, end: Int, step: Int): IArray[Int] = Array.range(start, end, step)
 
+ /** Returns an immutable 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 is repeatedly applied
+ * @return the immutable array returning `len` values in the sequence `start, f(start), f(f(start)), ...`
+ */
  def iterate[T: ClassTag](start: T, len: Int)(f: T => T): IArray[T] = Array.iterate(start, len)(f)
 
- def unapplySeq[T](x: IArray[T]): Option[IndexedSeq[T]] = Array.unapplySeq[T](x.asInstanceOf[Array[T]])
+ /** Returns a decomposition of the array into a sequence. This supports
+ * a pattern match like `{ case IArray(x,y,z) => println('3 elements')}`.
+ *
+ * @param x the selector value
+ * @return sequence wrapped in a [[scala.Some]], if `x` is a Seq, otherwise `None`
+ */
+ def unapplySeq[T](x: IArray[T]): Option[IndexedSeq[T]] = Array.unapplySeq[T](x.asInstanceOf[Array[T]])
 }