6 files changed, 37 insertions, 27 deletions
diff --git a/src/library/scala/collection/JavaConverters.scala b/src/library/scala/collection/JavaConverters.scala
index a4fa58b13c..875f6e1c02 100755
--- a/src/library/scala/collection/JavaConverters.scala
+++ b/src/library/scala/collection/JavaConverters.scala
@@ -37,8 +37,8 @@ import convert._
  *    val sl2 : scala.collection.mutable.Buffer[Int] = jl.asScala
  *    assert(sl eq sl2)
  *  }}}
- *  The following conversions also are supported, but the
- *  direction Scala to Java is done my a more specifically named method:
+ *  The following conversions are also supported, but the
+ *  direction from Scala to Java is done by the more specifically named methods:
  *  `asJavaCollection`, `asJavaEnumeration`, `asJavaDictionary`.
  *
  *  - `scala.collection.Iterable` <=> `java.util.Collection`
diff --git a/src/library/scala/collection/LinearSeq.scala b/src/library/scala/collection/LinearSeq.scala
index 49fbb902ab..5a7bb5891e 100644
--- a/src/library/scala/collection/LinearSeq.scala
+++ b/src/library/scala/collection/LinearSeq.scala
@@ -15,7 +15,14 @@ import generic._
 import mutable.Builder
 
 /** A base trait for linear sequences.
+ *
  *  $linearSeqInfo
+ *
+ *  @define  linearSeqInfo
+ *  Linear sequences have reasonably efficient `head`, `tail`, and `isEmpty` methods.
+ *  If these methods provide the fastest way to traverse the collection, a 
+ *  collection `Coll` that extends this trait should also extend
+ *  `LinearSeqOptimized[A, Coll[A]]`.
  */
 trait LinearSeq[+A] extends Seq[A]
                             with GenericTraversableTemplate[A, LinearSeq]
diff --git a/src/library/scala/collection/LinearSeqLike.scala b/src/library/scala/collection/LinearSeqLike.scala
index 6fb452797e..96e2135fd1 100644
--- a/src/library/scala/collection/LinearSeqLike.scala
+++ b/src/library/scala/collection/LinearSeqLike.scala
@@ -14,22 +14,10 @@ import scala.annotation.tailrec
 
 /** A template trait for linear sequences of type `LinearSeq[A]`.
  *
- *  $linearSeqInfo
- *
- *  This trait just implements `iterator` in terms of `isEmpty, ``head`, and `tail`.
- *  However, see `LinearSeqOptimized` for an implementation trait that overrides operations
+ *  This trait just implements `iterator` and `corresponds` in terms of `isEmpty, ``head`, and `tail`.
+ *  However, see `LinearSeqOptimized` for an implementation trait that overrides many more operations
  *  to make them run faster under the assumption of fast linear access with `head` and `tail`.
  *
- *  @define  linearSeqInfo
- *  Linear sequences are defined in terms of three abstract methods, which are assumed
- *  to have efficient implementations. These are:
- *  {{{
- *     def isEmpty: Boolean
- *     def head: A
- *     def tail: Repr
- *  }}}
- *  Here, `A` is the type of the sequence elements and `Repr` is the type of the sequence itself.
- *
  *  Linear sequences do not add any new methods to `Seq`, but promise efficient implementations
  *  of linear access patterns.
  *  @author  Martin Odersky
diff --git a/src/library/scala/collection/LinearSeqOptimized.scala b/src/library/scala/collection/LinearSeqOptimized.scala
index a28d796d5b..f834545ec6 100755
--- a/src/library/scala/collection/LinearSeqOptimized.scala
+++ b/src/library/scala/collection/LinearSeqOptimized.scala
@@ -13,10 +13,24 @@ import mutable.ListBuffer
 import immutable.List
 import scala.annotation.tailrec
 
-/** A template trait for linear sequences of type `LinearSeq[A]`  which optimizes
- *  the implementation of several methods under the assumption of fast linear access.
+/** A template trait for linear sequences of type `LinearSeq[A]` which optimizes
+ *  the implementation of various methods under the assumption of fast linear access.
+ *
+ *  $linearSeqOptim
+ *
+ *  @define  linearSeqOptim
+ *  Linear-optimized sequences implement most operations in in terms of three methods,
+ *  which are assumed to have efficient implementations. These are:
+ *  {{{
+ *     def isEmpty: Boolean
+ *     def head: A
+ *     def tail: Repr
+ *  }}}
+ *  Here, `A` is the type of the sequence elements and `Repr` is the type of the sequence itself.
+ *  Note that default implementations are provided via inheritance, but these
+ *  should be overridden for performance.
+ *
  *
- *  $linearSeqInfo
  */
 trait LinearSeqOptimized[+A, +Repr <: LinearSeqOptimized[A, Repr]] extends LinearSeqLike[A, Repr] { self: Repr =>
 
diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala
index fdfb1f2efc..329273df5b 100644
--- a/src/library/scala/collection/SeqLike.scala
+++ b/src/library/scala/collection/SeqLike.scala
@@ -140,7 +140,15 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[
     if (isEmpty) Iterator(repr)
     else new PermutationsItr
 
-  /** Iterates over combinations.
+  /** Iterates over combinations.  A _combination_ of length `n` is a subsequence of
+   *  the original sequence, with the elements taken in order.  Thus, `"xy"` and `"yy"`
+   *  are both length-2 combinations of `"xyy"`, but `"yx"` is not.  If there is
+   *  more than one way to generate the same subsequence, only one will be returned.
+   *
+   *  For example, `"xyyy"` has three different ways to generate `"xy"` depending on
+   *  whether the first, second, or third `"y"` is selected.  However, since all are 
+   *  identical, only one will be chosen.  Which of the three will be taken is an
+   *  implementation detail that is not defined.
    *
    *  @return   An Iterator which traverses the possible n-element combinations of this $coll.
    *  @example  `"abbbc".combinations(2) = Iterator(ab, ac, bb, bc)`
diff --git a/src/library/scala/collection/mutable/PriorityQueue.scala b/src/library/scala/collection/mutable/PriorityQueue.scala
index 4a9a5d4008..d3c4161e3b 100644
--- a/src/library/scala/collection/mutable/PriorityQueue.scala
+++ b/src/library/scala/collection/mutable/PriorityQueue.scala
@@ -247,13 +247,6 @@ class PriorityQueue[A](implicit val ord: Ordering[A])
    *  @return  a priority queue with the same elements.
    */
   override def clone(): PriorityQueue[A] = new PriorityQueue[A] ++= this.iterator
-
-  // def printstate() {
-  //   println("-----------------------")
-  //   println("Size: " + resarr.p_size0)
-  //   println("Internal array: " + resarr.p_array.toList)
-  //   println(toString)
-  // }
 }