documentation for scala.collection package, con...

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

1 files changed, 68 insertions, 1 deletions

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
+}