SI-8754 linear seqs aren't

LinearSeqLike still isn't exactly linear (LinearSeqOptimized is), but at least the docs now give reasonably correct information about what is actually going on.

3 files changed, 26 insertions, 17 deletions

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 ff7985bf0d..3288599221 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 =>