Improves PagedSeq API documentation.

1 files changed, 42 insertions, 37 deletions

diff --git a/src/library/scala/collection/immutable/PagedSeq.scala b/src/library/scala/collection/immutable/PagedSeq.scala
index 377412261c..8e14d9885d 100644
--- a/src/library/scala/collection/immutable/PagedSeq.scala
+++ b/src/library/scala/collection/immutable/PagedSeq.scala
@@ -17,12 +17,14 @@ import scala.util.matching.Regex
 /** The `PagedSeq` object defines a lazy implementations of
  *  a random access sequence.
  *
+ * Provides utility methods that return instances of `PagedSeq[Char]`.
+ * `fromIterator` and `fromIterable` provide generalised instances of `PagedSeq`
  *  @since 2.7
  */
 object PagedSeq {
   final val UndeterminedEnd = Int.MaxValue
 
-  /** Constructs a character sequence from a character iterator */
+  /** Constructs a paged sequence from an iterator */
   def fromIterator[T: ClassManifest](source: Iterator[T]): PagedSeq[T] =
     new PagedSeq[T]((data: Array[T], start: Int, len: Int) => {
       var i = 0
@@ -33,11 +35,11 @@ object PagedSeq {
       if (i == 0) -1 else i
     })
 
-  /** Constructs a character sequence from a character iterable */
+  /** Constructs a paged sequence from an iterable */
   def fromIterable[T: ClassManifest](source: Iterable[T]): PagedSeq[T] =
     fromIterator(source.iterator)
 
-  /** Constructs a character sequence from a string iterator */
+  /** Constructs a paged character sequence from a string iterator */
   def fromStrings(source: Iterator[String]): PagedSeq[Char] = {
     var current: String = ""
     def more(data: Array[Char], start: Int, len: Int): Int =
@@ -54,11 +56,11 @@ object PagedSeq {
     new PagedSeq(more(_: Array[Char], _: Int, _: Int))
   }
 
-  /** Constructs a character sequence from a string iterable */
+  /** Constructs a paged character sequence from a string iterable */
   def fromStrings(source: Iterable[String]): PagedSeq[Char] =
     fromStrings(source.iterator)
 
-  /** Constructs a character sequence from a line iterator
+  /** Constructs a paged character sequence from a line iterator
    *  Lines do not contain trailing `\n` characters; The method inserts
    *  a line separator `\n` between any two lines in the sequence.
    */
@@ -72,29 +74,29 @@ object PagedSeq {
     })
   }
 
-  /** Constructs a character sequence from a line iterable
+  /** Constructs a paged character sequence from a line iterable
    *  Lines do not contain trailing `\n` characters; The method inserts
    *  a line separator `\n` between any two lines in the sequence.
    */
   def fromLines(source: Iterable[String]): PagedSeq[Char] =
     fromLines(source.iterator)
 
-  /** Constructs a character sequence from an input reader
+  /** Constructs a paged character sequence from an input reader
    */
   def fromReader(source: Reader): PagedSeq[Char] =
     new PagedSeq(source.read(_: Array[Char], _: Int, _: Int))
 
-  /** Constructs a character sequence from an input file
+  /** Constructs a paged character sequence from an input file
    */
   def fromFile(source: File): PagedSeq[Char] =
     fromReader(new FileReader(source))
 
-  /** Constructs a character sequence from a file with given name
+  /** Constructs a paged character sequence from a file with given name
    */
   def fromFile(source: String): PagedSeq[Char] =
     fromFile(new File(source))
 
-  /** Constructs a character sequence from a scala.io.Source value
+  /** Constructs a paged character sequence from a scala.io.Source value
    */
   def fromSource(source: io.Source) =
     fromLines(source.getLines())
@@ -106,6 +108,13 @@ import PagedSeq._
 /** An implementation of lazily computed sequences, where elements are stored
  *  in "pages", i.e. arrays of fixed size.
  *
+ *  A paged sequence is constructed from a function that produces more elements when asked.
+ *  The producer function - `more`, is similar to the read method in java.io.Reader.
+ *  The `more` function takes three parameters: an array of elements, a start index, and an end index.
+ *  It should try to fill the array between start and end indices (excluding end index).
+ *  It returns the number of elements produced, or -1 if end of logical input stream was reached
+ *  before reading any element.
+ *
  *  @tparam T     the type of the elements contained in this paged sequence, with a `ClassManifest` context bound.
  *
  *  @author Martin Odersky
@@ -122,13 +131,6 @@ class PagedSeq[T: ClassManifest] protected(
   end: Int)
 extends scala.collection.IndexedSeq[T]
 {
-  /**  A paged sequence is constructed from a method that produces more characters when asked.
-   *  The producer method is analogous to the read method in java.io.Reader.
-   *  It takes three parameters: an array of characters, a start index, and an end index.
-   *  It should try to fill the array between start and end indices (not including end index).
-   *  It returns the number of characters produced, or -1 if end of logical input stream was reached
-   *  before any character was read.
-   */
   def this(more: (Array[T], Int, Int) => Int) = this(more, new Page[T](0), 0, UndeterminedEnd)
 
   private var current: Page[T] = first1
@@ -148,21 +150,22 @@ extends scala.collection.IndexedSeq[T]
     current
   }
 
-  /** The length of the character sequence
-   *  Note: calling this method will force sequence to be read until the end.
+  /** The length of the paged sequence
+   *  @note Calling this method will force the entire sequence to be read.
    */
   def length: Int = {
     while (!latest.isLast) addMore()
     (latest.end min end) - start
   }
 
-  /** The character at position `index`.
+  /** The element at position `index`.
    */
   def apply(index: Int) =
     if (isDefinedAt(index)) page(index + start)(index + start)
     else throw new IndexOutOfBoundsException(index.toString)
 
-  /** Is character sequence defined at `index`?
+  /** Predicate method to check if an element is defined
+   *  at position `index` of the current sequence.
    *  Unlike `length` this operation does not force reading
    *  a lazy sequence to the end.
    */
@@ -171,8 +174,10 @@ extends scala.collection.IndexedSeq[T]
       val p = page(index + start); index + start < p.end
     }
 
-  /** the subsequence from index `start` up to and excluding
-   *  the minimum of index `end` and the length of the current sequence.
+   /** The subsequence from index `start` up to `end -1` if `end`
+   *   is lesser than the length of the current sequence and up to
+   *   length of the sequence otherwise. This is limited up to the length
+   *   of the current sequence if `end` is larger than its length.
    */
   override def slice(_start: Int, _end: Int): PagedSeq[T] = {
     page(start)
@@ -183,8 +188,8 @@ extends scala.collection.IndexedSeq[T]
     new PagedSeq(more, f, s, e)
   }
 
-  /** the subsequence from index `start` up to the
-   *  length of the current sequence.
+  /** The subsequence from index `start` up to
+   *  the length of the current sequence.
    */
   def slice(start: Int): PagedSeq[T] = slice(start, UndeterminedEnd)
 
@@ -209,40 +214,40 @@ private class Page[T: ClassManifest](val num: Int) {
   /** A later page in the sequence, serves a cache for pointing to last page */
   var later : Page[T] = this
 
-  /** The number of characters read into this page */
+  /** The number of elements read into this page */
   var filled: Int = 0
 
-  /** Is this page the permamnently last one in the sequence? Only true once `more`
-   *  method has returned -1 to signal end of input. */
+  /** Set true if the current page is the last in the sequence or if
+  *   the `more` function returned -1 signalling end of input. */
   var isLast: Boolean = false
 
-  /** The character array */
+  /** The element array */
   final val data = new Array[T](PageSize)
 
-  /** The index of the first character in this page relative to the whole sequence */
+  /** The index of the first element in this page relative to the whole sequence */
   final def start = num * PageSize
 
-  /** The index of the character following the last character in this page relative
+  /** The index of the element following the last element in this page relative
    *  to the whole sequence */
   final def end = start + filled
 
-  /** The currently last page in the sequence; might change as more characters are appended */
+  /** The last page as currently present in the sequence; This can change as more
+   *  elements get appended to the sequence.  */
   final def latest: Page[T] = {
     if (later.next != null) later = later.next.latest
     later
   }
 
-  /** The character at given sequence index.
+  /** The element at the given sequence index.
    *  That index is relative to the whole sequence, not the page. */
   def apply(index: Int) = {
     if (index < start || index - start >= filled) throw new IndexOutOfBoundsException(index.toString)
     data(index - start)
   }
 
-  /** produces more characters by calling `more` and appends them on the current page,
-   *  or fills a subsequent page if current page is full
-   *  pre: if current page is full, it is the last one in the sequence.
-   */
+  /** Produces more elements by calling `more` and adds them on the current page,
+   *  or fills a subsequent page if current page is full.
+   *  @note If current page is full, it is the last one in the sequence.  */
   final def addMore(more: (Array[T], Int, Int) => Int): Page[T] =
     if (filled == PageSize) {
       next = new Page[T](num + 1)