allowed $super variables in doc comment; some m...

allowed $super variables in doc comment; some more documentation of
collection classes.

1 files changed, 112 insertions, 47 deletions

diff --git a/src/library/scala/collection/IndexedSeqLike.scala b/src/library/scala/collection/IndexedSeqLike.scala
index 7041078229..7951dc99c5 100644
--- a/src/library/scala/collection/IndexedSeqLike.scala
+++ b/src/library/scala/collection/IndexedSeqLike.scala
@@ -15,23 +15,31 @@ import generic._
 import mutable.ArrayBuffer
 import scala.annotation.tailrec
 
-/** Sequences that support O(1) element access and O(1) length computation.
- *  This class does not add any methods to Seq but overrides several
- *  methods with optimized implementations.
+/** A template trait for indexed sequences of type `IndexedSeq[A]`.
  *
+ *  $indexedSeqInfo
  *  @author Sean McDirmid
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.8
+ *  @define indexedSeqInfo
+ *  Indexed sequences support constant-time or near constant-time element
+ *  access and length computation.
+ *
+ *  Indexed sequences do not define any new methods wrt `Seq`. However, some `Seq` methods
+ *  are overridden with optimized implementations.
+ *
+ *  @tparam A    the element type of the $coll
+ *  @tparam Repr the type of the actual $coll containing the elements.
  */
 trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
 
   override protected[this] def thisCollection: IndexedSeq[A] = this.asInstanceOf[IndexedSeq[A]]
   override protected[this] def toCollection(repr: Repr): IndexedSeq[A] = repr.asInstanceOf[IndexedSeq[A]]
 
-  // Overridden methods from IterableLike
-
-  /** The iterator returned by the iterator method
+  /** The class of the iterator returned by the `iterator` method.
+   *  multiple `take`, `drop`, and `slice` operations on this iterator are bunched
+   *  together for better efficiency.
    */
   @serializable @SerialVersionUID(1756321872811029277L)
   protected class Elements(start: Int, end: Int) extends BufferedIterator[A] {
@@ -49,36 +57,48 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
     def head =
       if (i < end) self(i) else Iterator.empty.next
 
-    /** drop is overridden to enable fast searching in the middle of random access sequences */
+    /** $super
+     *  @note `drop` is overridden to enable fast searching in the middle of indexed sequences.
+     */
     override def drop(n: Int): Iterator[A] =
       if (n > 0) new Elements(start + n, end) else this
 
-    /** take is overridden to be symmetric to drop */
+    /** $super
+     *  @note `take` is overridden to be symmetric to `drop`.
+     */
     override def take(n: Int): Iterator[A] =
       if (n <= 0) Iterator.empty.buffered
       else if (start + n < end) new Elements(start, start + n)
       else this
   }
 
-  override def iterator: Iterator[A] = new Elements(0, length)
+  override /*IterableLike*/
+  def iterator: Iterator[A] = new Elements(0, length)
 
-  override def isEmpty: Boolean = { length == 0 }
+  override /*IterableLike*/
+  def isEmpty: Boolean = { length == 0 }
 
-  override def foreach[U](f: A =>  U): Unit = {
+  override /*IterableLike*/
+  def foreach[U](f: A =>  U): Unit = {
     var i = 0
     val len = length
     while (i < len) { f(this(i)); i += 1 }
   }
 
-  override def forall(p: A => Boolean): Boolean = prefixLength(p(_)) == length
-  override def exists(p: A => Boolean): Boolean = prefixLength(!p(_)) != length
+  override /*IterableLike*/
+  def forall(p: A => Boolean): Boolean = prefixLength(p(_)) == length
 
-  override def find(p: A => Boolean): Option[A] = {
+  override /*IterableLike*/
+  def exists(p: A => Boolean): Boolean = prefixLength(!p(_)) != length
+
+  override /*IterableLike*/
+  def find(p: A => Boolean): Option[A] = {
     val i = prefixLength(!p(_))
     if (i < length) Some(this(i)) else None
   }
 /*
-  override def mapFind[B](f: A => Option[B]): Option[B] = {
+  override /*IterableLike*/
+  def mapFind[B](f: A => Option[B]): Option[B] = {
     var i = 0
     var res: Option[B] = None
     val len = length
@@ -99,16 +119,24 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
     if (start == end) z
     else foldr(start, end - 1, op(this(end - 1), z), op)
 
-  override def foldLeft[B](z: B)(op: (B, A) => B): B =
+  override /*TraversableLike*/
+  def foldLeft[B](z: B)(op: (B, A) => B): B =
     foldl(0, length, z, op)
-  override def foldRight[B](z: B)(op: (A, B) => B): B =
+
+  override /*IterableLike*/
+  def foldRight[B](z: B)(op: (A, B) => B): B =
     foldr(0, length, z, op)
-  override def reduceLeft[B >: A](op: (B, A) => B): B =
+
+  override /*TraversableLike*/
+  def reduceLeft[B >: A](op: (B, A) => B): B =
     if (length > 0) foldl(1, length, this(0), op) else super.reduceLeft(op)
-  override def reduceRight[B >: A](op: (A, B) => B): B =
+
+  override /*IterableLike*/
+  def reduceRight[B >: A](op: (A, B) => B): B =
     if (length > 0) foldr(0, length - 1, this(length - 1), op) else super.reduceRight(op)
 
-  override def zip[A1 >: A, B, That](that: Iterable[B])(implicit bf: CanBuildFrom[Repr, (A1, B), That]): That = that match {
+  override /*IterableLike*/
+  def zip[A1 >: A, B, That](that: Iterable[B])(implicit bf: CanBuildFrom[Repr, (A1, B), That]): That = that match {
     case that: IndexedSeq[_] =>
       val b = bf(repr)
       var i = 0
@@ -123,7 +151,8 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
       super.zip[A1, B, That](that)(bf)
   }
 
-  override def zipWithIndex[A1 >: A, That](implicit bf: CanBuildFrom[Repr, (A1, Int), That]): That = {
+  override /*IterableLike*/
+  def zipWithIndex[A1 >: A, That](implicit bf: CanBuildFrom[Repr, (A1, Int), That]): That = {
     val b = bf(repr)
     val len = length
     b.sizeHint(len)
@@ -135,7 +164,8 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
     b.result
   }
 
-  override def slice(from: Int, until: Int): Repr = {
+  override /*IterableLike*/
+  def slice(from: Int, until: Int): Repr = {
     var i = from max 0
     val end = until min length
     val b = newBuilder
@@ -147,20 +177,44 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
     b.result
   }
 
-  override def head: A = if (isEmpty) super.head else this(0)
-  override def tail: Repr = if (isEmpty) super.tail else slice(1, length)
-  override def last: A = if (length > 0) this(length - 1) else super.last
-  override def init: Repr = if (length > 0) slice(0, length - 1) else super.init
-  override def take(n: Int): Repr = slice(0, n)
-  override def drop(n: Int): Repr = slice(n, length)
-  override def takeRight(n: Int): Repr = slice(length - n, length)
-  override def dropRight(n: Int): Repr = slice(0, length - n)
-  override def splitAt(n: Int): (Repr, Repr) = (take(n), drop(n))
-  override def takeWhile(p: A => Boolean): Repr = take(prefixLength(p))
-  override def dropWhile(p: A => Boolean): Repr = drop(prefixLength(p))
-  override def span(p: A => Boolean): (Repr, Repr) = splitAt(prefixLength(p))
-
-  override def sameElements[B >: A](that: Iterable[B]): Boolean = that match {
+  override /*IterableLike*/
+  def head: A = if (isEmpty) super.head else this(0)
+
+  override /*TraversableLike*/
+  def tail: Repr = if (isEmpty) super.tail else slice(1, length)
+
+  override /*TraversableLike*/
+  def last: A = if (length > 0) this(length - 1) else super.last
+
+  override /*IterableLike*/
+  def init: Repr = if (length > 0) slice(0, length - 1) else super.init
+
+  override /*TraversableLike*/
+  def take(n: Int): Repr = slice(0, n)
+
+  override /*TraversableLike*/
+  def drop(n: Int): Repr = slice(n, length)
+
+  override /*IterableLike*/
+  def takeRight(n: Int): Repr = slice(length - n, length)
+
+  override /*IterableLike*/
+  def dropRight(n: Int): Repr = slice(0, length - n)
+
+  override /*TraversableLike*/
+  def splitAt(n: Int): (Repr, Repr) = (take(n), drop(n))
+
+  override /*IterableLike*/
+  def takeWhile(p: A => Boolean): Repr = take(prefixLength(p))
+
+  override /*TraversableLike*/
+  def dropWhile(p: A => Boolean): Repr = drop(prefixLength(p))
+
+  override /*TraversableLike*/
+  def span(p: A => Boolean): (Repr, Repr) = splitAt(prefixLength(p))
+
+  override /*IterableLike*/
+  def sameElements[B >: A](that: Iterable[B]): Boolean = that match {
     case that: IndexedSeq[_] =>
       val len = length
       len == that.length && {
@@ -172,7 +226,8 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
       super.sameElements(that)
   }
 
-  override def copyToArray[B >: A](xs: Array[B], start: Int, len: Int) {
+  override /*IterableLike*/
+  def copyToArray[B >: A](xs: Array[B], start: Int, len: Int) {
     var i = 0
     var j = start
     val end = length min len min (xs.length - start)
@@ -186,9 +241,11 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
 
   // Overridden methods from Seq
 
-  override def lengthCompare(len: Int): Int = length - len
+  override /*SeqLike*/
+  def lengthCompare(len: Int): Int = length - len
 
-  override def segmentLength(p: A => Boolean, from: Int): Int = {
+  override /*SeqLike*/
+  def segmentLength(p: A => Boolean, from: Int): Int = {
     val start = from
     val len = length
     var i = start
@@ -198,18 +255,21 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
 
   private def negLength(n: Int) = if (n == length) -1 else n
 
-  override def indexWhere(p: A => Boolean, from: Int): Int = {
+  override /*SeqLike*/
+  def indexWhere(p: A => Boolean, from: Int): Int = {
     val start = from max 0
     negLength(start + segmentLength(!p(_), start))
   }
 
-  override def lastIndexWhere(p: A => Boolean, end: Int): Int = {
+  override /*SeqLike*/
+  def lastIndexWhere(p: A => Boolean, end: Int): Int = {
     var i = end
     while (i >= 0 && !p(this(i))) i -= 1
     i
   }
 
-  override def reverse: Repr = {
+  override /*SeqLike*/
+  def reverse: Repr = {
     val b = newBuilder
     b.sizeHint(length)
     var i = length
@@ -220,7 +280,8 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
     b.result
   }
 
-  override def reverseIterator: Iterator[A] = new Iterator[A] {
+  override /*SeqLike*/
+  def reverseIterator: Iterator[A] = new Iterator[A] {
     private var i = self.length
     def hasNext: Boolean = 0 < i
     def next: A =
@@ -230,7 +291,8 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
       } else Iterator.empty.next
   }
 
-  override def startsWith[B](that: Seq[B], offset: Int): Boolean = that match {
+  override /*SeqLike*/
+  def startsWith[B](that: Seq[B], offset: Int): Boolean = that match {
     case that: IndexedSeq[_] =>
       var i = offset
       var j = 0
@@ -254,7 +316,8 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
       !thatElems.hasNext
   }
 
-  override def endsWith[B](that: Seq[B]): Boolean = that match {
+  override /*SeqLike*/
+  def endsWith[B](that: Seq[B]): Boolean = that match {
     case that: IndexedSeq[_] =>
       var i = length - 1
       var j = that.length - 1
@@ -272,13 +335,15 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
       super.endsWith(that)
   }
 
-  override def view = new IndexedSeqView[A, Repr] {
+  override /*SeqLike*/
+  def view = new IndexedSeqView[A, Repr] {
     protected lazy val underlying = self.repr
     override def iterator = self.iterator
     override def length = self.length
     override def apply(idx: Int) = self.apply(idx)
   }
 
-  override def view(from: Int, until: Int) = view.slice(from, until)
+  override /*SeqLike*/
+  def view(from: Int, until: Int) = view.slice(from, until)
 }