fix documentation of lengthCompare method

3 files changed, 27 insertions, 6 deletions

diff --git a/src/library/scala/List.scala b/src/library/scala/List.scala
index 0198813914..f6f10161d6 100644
--- a/src/library/scala/List.scala
+++ b/src/library/scala/List.scala
@@ -456,7 +456,16 @@ sealed abstract class List[+A] extends Seq[A] {
    */
   def head: A
 
-  /** returns length - l, without calling length
+  /** Result of comparing <code>length</code> with operand <code>l</code>.
+   *  returns <code>x</code> where
+   *  <code>x &lt; 0</code>    iff    <code>this.length &lt; l</code>
+   *  <code>x == 0</code>   iff    <code>this.length == l</code>
+   *  <code>x &gt; 0</code>    iff    <code>this.length &gt; that</code>.
+   *
+   *  This method is used by matching streams against right-ignoring (...,_*) patterns.
+   *
+   *  This method does not call <code>List.length</code>, it works for <code>O(l)</code>,
+   *  not for <code>O(length)</code>.
    */
   override def lengthCompare(l: Int) = {
     if (isEmpty) 0 - l
diff --git a/src/library/scala/Seq.scala b/src/library/scala/Seq.scala
index c3720427e1..3b184a1ba5 100644
--- a/src/library/scala/Seq.scala
+++ b/src/library/scala/Seq.scala
@@ -140,7 +140,13 @@ trait Seq[+A] extends AnyRef with PartialFunction[Int, A] with Collection[A] {
    */
   def length: Int
 
-  /** Returns length - l. This method is used by matching streams against right-ignoring (...,_*) patterns.
+  /** Result of comparing <code>length</code> with operand <code>l</code>.
+   *  returns <code>x</code> where
+   *  <code>x &lt; 0</code>    iff    <code>this.length &lt; l</code>
+   *  <code>x == 0</code>   iff    <code>this.length == l</code>
+   *  <code>x &gt; 0</code>    iff    <code>this.length &gt; that</code>.
+   *
+   *  This method is used by matching streams against right-ignoring (...,_*) patterns.
    *  Lazy sequences should override this method if length forces evaluation of the stream.
    */
   def lengthCompare(l: Int): Int = length - l
diff --git a/src/library/scala/Stream.scala b/src/library/scala/Stream.scala
index 541ffd833d..6765ec1db8 100644
--- a/src/library/scala/Stream.scala
+++ b/src/library/scala/Stream.scala
@@ -243,10 +243,16 @@ abstract class Stream[+A] extends Seq.Projection[A] {
     len
   }
 
-  /** Returns
-   *   - (length - l) if l >= length
-   *   - 1 otherwise
-   *  This method does not call Stream.length.
+  /** Result of comparing <code>length</code> with operand <code>l</code>.
+   *  returns <code>x</code> where
+   *  <code>x &lt; 0</code>    iff    <code>this.length &lt; l</code>
+   *  <code>x == 0</code>   iff    <code>this.length == l</code>
+   *  <code>x &gt; 0</code>    iff    <code>this.length &gt; that</code>.
+   *
+   *  This method is used by matching streams against right-ignoring (...,_*) patterns.
+   *
+   *  This method does not call <code>Stream.length</code>, it works for <code>O(l)</code>,
+   *  not for <code>O(length)</code> and does not force full Stream evaluation.
    */
   final override def lengthCompare(l: Int) = {
     if (isEmpty) 0 - l