1 files changed, 23 insertions, 15 deletions
diff --git a/src/library/scala/collection/package.scala b/src/library/scala/collection/package.scala
index 13fe7a79c4..856f901b77 100644
--- a/src/library/scala/collection/package.scala
+++ b/src/library/scala/collection/package.scala
@@ -13,8 +13,11 @@ package scala
  *
  * == Guide ==
  *
- * A detailed guide for the collections library is available
+ * A detailed guide for using the collections library is available
  * at [[http://docs.scala-lang.org/overviews/collections/introduction.html]].
+ * Developers looking to extend the collections library can find a description
+ * of its architecture at
+ * [[http://docs.scala-lang.org/overviews/core/architecture-of-scala-collections.html]].
  *
  * == Using Collections ==
  *
@@ -31,24 +34,25 @@ package scala
  * 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)
+ * res0: Array[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)
+ * res1: List[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.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:
+ * The most common way to create a collection is to use its companion object as
+ * a factory. The three most commonly used collections are
+ * [[scala.collection.Seq]], [[scala.collection.immutable.Set]], and
+ * [[scala.collection.immutable.Map]].
+ * They can be used directly as shown below since their companion objects are
+ * all available as type aliases in either the [[scala]] package or in
+ * `scala.Predef`. New collections are created like this:
  * {{{
  * scala> val seq = Seq(1,2,3,4,1)
  * seq: Seq[Int] = List(1, 2, 3, 4, 1)
@@ -56,12 +60,12 @@ package scala
  * 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))
+ * scala> val map = Map(1 -> "one", 2 -> "two", 3 -> "three", 2 -> "too")
+ * map: scala.collection.immutable.Map[Int,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
+ * It is also typical to prefer the [[scala.collection.immutable]] collections
+ * over those in [[scala.collection.mutable]]; the types aliased in
  * the `scala.Predef` object are the immutable versions.
  *
  * Also note that the collections library was carefully designed to include several implementations of
@@ -74,9 +78,13 @@ package scala
  *
  * === 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.
+ * The [[scala.collection.JavaConversions]] object provides implicit defs that
+ * will allow mostly seamless integration between APIs using Java Collections
+ * and the Scala collections library.
  *
+ * Alternatively the [[scala.collection.JavaConverters]] object provides a collection
+ * of decorators that allow converting between Scala and Java collections using `asScala`
+ * and `asJava` methods.
  */
 package object collection {
   import scala.collection.generic.CanBuildFrom