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]])
 }