Additional documentation for the Array type, wi...

Additional documentation for the Array type, with short code examples of
construction, access and update. Also links to ArrayOps and WrappedArray
in order to explain where the additional collections operations come
from. Contributed by [email protected].

Author: paulp

src/library/scala/Array.scala

@@ -476,11 +476,41 @@ object Array extends FallbackArrayBuilding {
     fromFunction(i => fromFunction(f(i, _, _, _, _))(n2, n3, n4, n5))(n1)
 }
 
-/** Represents polymorphic arrays. `Array[T]` is Scala's representation
+/** Arrays are mutable, indexed collections of values. `Array[T]` is Scala's representation
  *  for Java's `T[]`.
  *
+ *  {{{
+ *  val numbers = Array(1, 2, 3, 4)
+ *  val first = numbers(0) // read the first element
+ *  numbers.update(3, 100) // replace the 4th array element with 100
+ *  val biggerNumbers = numbers.map(_ * 2) // multiply all numbers by two
+ *  }}}
+ *
+ *  Two implicit conversions exist in [[scala.Predef]] that are frequently applied to arrays: a conversion
+ *  to [[scala.collection.mutable.ArrayOps]] and a conversion
+ *  to [[scala.collection.mutable.WrappedArray]] (a subtype of [[scala.collections.Seq]]).
+ *  Both types make available many of the standard operations found in the Scala collections API.
+ *  The conversion to `ArrayOps` is temporary, as all operations defined on `ArrayOps` return an `Array`,
+ *  while the conversion to `WrappedArray` is permanent as all operations return a `WrappedArray`.
+ *
+ *  The conversion to `ArrayOps` takes priority over the conversion to `WrappedArray`. For instance,
+ *  consider the following code:
+ *
+ *  {{{
+ *  val arr = Array(1, 2, 3)
+ *  val arrReversed = arr.reverse
+ *  val seqReversed : Seq[Int] = arr.reverse
+ *  }}}
+ *
+ *  Value `arrReversed` will be of type `Array[Int]`, with an implicit conversion to `ArrayOps` occurring
+ *  to perform the `reverse` operation. The value of `seqReversed`, on the other hand, will be computed
+ *  by converting to `WrappedArray` first and invoking the variant of `reverse` that returns another
+ *  `WrappedArray`.
+ *
  *  @author Martin Odersky
  *  @version 1.0
+ *  @see [[http://www.scala-lang.org/docu/files/collections-api/collections_38.html "The Scala 2.8 Collections API"]]
+ *  by Martin Odersky for more information.
  */
 final class Array[T](_length: Int) extends java.io.Serializable with java.lang.Cloneable {