Documented immutable.*. no review

10 files changed, 152 insertions, 82 deletions

diff --git a/src/library/scala/collection/generic/SetFactory.scala b/src/library/scala/collection/generic/SetFactory.scala
index 6a237d453c..87de1cec32 100644
--- a/src/library/scala/collection/generic/SetFactory.scala
+++ b/src/library/scala/collection/generic/SetFactory.scala
@@ -14,7 +14,7 @@ package generic
 
 import mutable.{Builder, AddingBuilder}
 
-/** A template for companion objects of <code>Set</code> and subclasses
+/** A template for companion objects of `Set` and subclasses
  *  thereof.
  *
  *  @define coll set
diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala
index 4c90a89104..9b801f26cb 100644
--- a/src/library/scala/collection/immutable/BitSet.scala
+++ b/src/library/scala/collection/immutable/BitSet.scala
@@ -56,6 +56,8 @@ abstract class BitSet extends Set[Int]
 }
 
 /** $factoryInfo
+ *  @define Coll immutable.BitSet
+ *  @define coll immutable bitset
  */
 object BitSet extends BitSetFactory[BitSet] {
 
diff --git a/src/library/scala/collection/immutable/Stack.scala b/src/library/scala/collection/immutable/Stack.scala
index aa7ee908d6..0323db7211 100644
--- a/src/library/scala/collection/immutable/Stack.scala
+++ b/src/library/scala/collection/immutable/Stack.scala
@@ -42,6 +42,10 @@ object Stack extends SeqFactory[Stack] {
  *  @since   1
  *  @define Coll immutable.Stack
  *  @define coll immutable stack
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(1976480595012942526L)
 class Stack[+A] protected (protected val elems: List[A]) extends LinearSeq[A]
diff --git a/src/library/scala/collection/immutable/Stream.scala b/src/library/scala/collection/immutable/Stream.scala
index 7f0b21050a..50fa07c2cf 100644
--- a/src/library/scala/collection/immutable/Stream.scala
+++ b/src/library/scala/collection/immutable/Stream.scala
@@ -16,27 +16,33 @@ import generic._
 import mutable.{Builder, StringBuilder, LazyBuilder, ListBuffer}
 import scala.annotation.tailrec
 
-/**
- * <p>The class <code>Stream</code> implements lazy lists where elements
- * are only evaluated when they are needed. Here is an example:</p>
- * <pre>
- * <b>object</b> Main <b>extends</b> Application {
+/** The class `Stream` implements lazy lists where elements
+ *  are only evaluated when they are needed. Here is an example:
  *
- *   <b>def</b> from(n: Int): Stream[Int] =
- *     Stream.cons(n, from(n + 1))
+ *  {{{
+ *  object Main extends Application {
  *
- *   <b>def</b> sieve(s: Stream[Int]): Stream[Int] =
- *     Stream.cons(s.head, sieve(s.tail filter { _ % s.head != 0 }))
+ *    def from(n: Int): Stream[Int] =
+ *      Stream.cons(n, from(n + 1))
  *
- *   <b>def</b> primes = sieve(from(2))
+ *    def sieve(s: Stream[Int]): Stream[Int] =
+ *      Stream.cons(s.head, sieve(s.tail filter { _ % s.head != 0 }))
  *
- *   primes take 10 print
- * }
- * </pre>
+ *    def primes = sieve(from(2))
  *
- * @author Martin Odersky, Matthias Zenger
- * @version 1.1 08/08/03
- * @since   2.8
+ *    primes take 10 print
+ *  }
+ *  }}}
+ *
+ *  @tparam A    the type of the elements contained in this stream.
+ *
+ *  @author Martin Odersky, Matthias Zenger
+ *  @version 1.1 08/08/03
+ *  @since   2.8
+ *  @define Coll Stream
+ *  @define coll stream
+ *  @define orderDependent
+ *  @define orderDependentFold
  */
 abstract class Stream[+A] extends LinearSeq[A]
                              with GenericTraversableTemplate[A, Stream]
@@ -68,6 +74,7 @@ self =>
 
   /** The stream resulting from the concatenation of this stream with the argument stream.
    *  @param rest   The stream that gets appended to this stream
+   *  @return       The stream containing elements of this stream and the traversable object.
    */
   def append[B >: A](rest: => Traversable[B]): Stream[B] =
     if (isEmpty) rest.toStream else new Stream.Cons(head, tail append rest)
@@ -82,7 +89,7 @@ self =>
   /** Prints elements of this stream one by one, separated by commas. */
   def print() { print(", ") }
 
-  /** Prints elements of this stream one by one, separated by <code>sep</code>.
+  /** Prints elements of this stream one by one, separated by `sep`.
    *  @param sep   The separator string printed between consecutive elements.
    */
   def print(sep: String) {
@@ -138,7 +145,7 @@ self =>
     )
 
   /** Returns the stream resulting from applying the given function
-   *  <code>f</code> to each element of this stream.
+   *  `f` to each element of this stream.
    *
    *  @param f function to apply to each element.
    *  @return  <code>f(a<sub>0</sub>), ..., f(a<sub>n</sub>)</code> if this
@@ -150,10 +157,11 @@ self =>
       else new Stream.Cons(f(head), asStream[B](tail map f))
     )
 
-  /** Applies the given function <code>f</code> to each element of
+  /** Applies the given function `f` to each element of
    *  this stream, then concatenates the results.
    *
-   *  @param f the function to apply on each element.
+   *  @param f  the function to apply on each element.
+   *  @param bf $bfinfo
    *  @return  <code>f(a<sub>0</sub>) ::: ... ::: f(a<sub>n</sub>)</code> if
    *           this stream is <code>[a<sub>0</sub>, ..., a<sub>n</sub>]</code>.
    */
diff --git a/src/library/scala/collection/immutable/StringLike.scala b/src/library/scala/collection/immutable/StringLike.scala
index 8068267dd2..f12ddebd08 100644
--- a/src/library/scala/collection/immutable/StringLike.scala
+++ b/src/library/scala/collection/immutable/StringLike.scala
@@ -17,8 +17,8 @@ import mutable.Builder
 import scala.util.matching.Regex
 import scala.math.ScalaNumber
 
-/**
- * @since 2.8
+/** A companion object for the `StringLike` containing some constants.
+ *  @since 2.8
  */
 object StringLike {
 
@@ -31,8 +31,17 @@ object StringLike {
 
 import StringLike._
 
-/**
- * @since 2.8
+/** A trait describing stringlike collections.
+ *
+ *  @tparam Repr   The type of the actual collection inheriting `StringLike`.
+ *
+ *  @since 2.8
+ *  @define Coll String
+ *  @define coll string
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 trait StringLike[+Repr] extends IndexedSeqOptimized[Char, Repr] with Ordered[String] {
 self =>
@@ -62,15 +71,15 @@ self =>
   private def isLineBreak(c: Char) = c == LF || c == FF
 
   /**
-   *    Strip trailing line end character from this string if it has one.
+   *  Strip trailing line end character from this string if it has one.
    *
-   *    A line end character is one of
-   *    <ul style="list-style-type: none;">
-   *      <li>LF - line feed   (0x0A hex)</li>
-   *      <li>FF - form feed   (0x0C hex)</li>
-   *    </ul>
-   *    If a line feed character LF is preceded by a carriage return CR
-   *    (0x0D hex), the CR character is also stripped (Windows convention).
+   *  A line end character is one of
+   *  <ul style="list-style-type: none;">
+   *    <li>LF - line feed   (0x0A hex)</li>
+   *    <li>FF - form feed   (0x0C hex)</li>
+   *  </ul>
+   *  If a line feed character LF is preceded by a carriage return CR
+   *  (0x0D hex), the CR character is also stripped (Windows convention).
    */
   def stripLineEnd: String = {
     val len = toString.length
@@ -112,15 +121,15 @@ self =>
   }
 
   /** Return all lines in this string in an iterator, excluding trailing line
-   *  end characters, i.e. apply <code>.stripLineEnd</code> to all lines
-   *  returned by <code>linesWithSeparators</code>.
+   *  end characters, i.e. apply `.stripLineEnd` to all lines
+   *  returned by `linesWithSeparators`.
    */
   def lines: Iterator[String] =
     linesWithSeparators map (line => new WrappedString(line).stripLineEnd)
 
   /** Return all lines in this string in an iterator, excluding trailing line
-   *  end characters, i.e. apply <code>.stripLineEnd</code> to all lines
-   *  returned by <code>linesWithSeparators</code>.
+   *  end characters, i.e. apply `.stripLineEnd` to all lines
+   *  returned by `linesWithSeparators`.
    */
   def linesIterator: Iterator[String] =
     linesWithSeparators map (line => new WrappedString(line).stripLineEnd)
@@ -135,12 +144,12 @@ self =>
       new String(chars)
     }
 
-  /** Returns this string with the given <code>prefix</code> stripped. */
+  /** Returns this string with the given `prefix` stripped. */
   def stripPrefix(prefix: String) =
     if (toString.startsWith(prefix)) toString.substring(prefix.length)
     else toString
 
-  /** Returns this string with the given <code>suffix</code> stripped. */
+  /** Returns this string with the given `suffix` stripped. */
   def stripSuffix(suffix: String) =
     if (toString.endsWith(suffix)) toString.substring(0, toString.length() - suffix.length)
     else toString
@@ -150,7 +159,7 @@ self =>
    *
    *    <blockquote>
    *       Strip a leading prefix consisting of blanks or control characters
-   *       followed by <code>marginChar</code> from the line.
+   *       followed by `marginChar` from the line.
    *    </blockquote>
    */
   def stripMargin(marginChar: Char): String = {
@@ -170,7 +179,7 @@ self =>
    *
    *    <blockquote>
    *       Strip a leading prefix consisting of blanks or control characters
-   *       followed by <code>|</code> from the line.
+   *       followed by `|` from the line.
    *    </blockquote>
    */
   def stripMargin: String = stripMargin('|')
@@ -230,7 +239,7 @@ self =>
    *
    *    The interpretation of the formatting patterns is described in
    *    <a href="" target="contentFrame" class="java/util/Formatter">
-   *    <code>java.util.Formatter</code></a>, with the addition that
+   *    `java.util.Formatter`</a>, with the addition that
    *    classes deriving from `ScalaNumber` (such as `scala.BigInt` and
    *    `scala.BigDecimal`) are unwrapped to pass a type which `Formatter`
    *    understands.
@@ -249,7 +258,7 @@ self =>
    *
    *    The interpretation of the formatting patterns is described in
    *    <a href="" target="contentFrame" class="java/util/Formatter">
-   *    <code>java.util.Formatter</code></a>, with the addition that
+   *    `java.util.Formatter`</a>, with the addition that
    *    classes deriving from `ScalaNumber` (such as `scala.BigInt` and
    *    `scala.BigDecimal`) are unwrapped to pass a type which `Formatter`
    *    understands.
diff --git a/src/library/scala/collection/immutable/StringOps.scala b/src/library/scala/collection/immutable/StringOps.scala
index 4949eb7056..2bdbf672cd 100644
--- a/src/library/scala/collection/immutable/StringOps.scala
+++ b/src/library/scala/collection/immutable/StringOps.scala
@@ -15,15 +15,19 @@ package immutable
 import mutable.StringBuilder
 
 /**
- * This class serves as a wrapper providing `String`s with all the operations
- * found in indexed sequences. Where needed, instances of `String` object
- * are implicitly converted into this class.
+ *  This class serves as a wrapper providing `String`s with all the operations
+ *  found in indexed sequences. Where needed, instances of `String` object
+ *  are implicitly converted into this class.
  *
- * The difference between this class and `WrappedString` is that calling transformer
- * methods such as `filter` and `map` will yield a `String` object, whereas a
- * `WrappedString` will remain a `WrappedString`.
+ *  The difference between this class and `WrappedString` is that calling transformer
+ *  methods such as `filter` and `map` will yield a `String` object, whereas a
+ *  `WrappedString` will remain a `WrappedString`.
  *
- * @since 2.8
+ *  @param repr     the actual representation of this string operations object.
+ *
+ *  @since 2.8
+ *  @define Coll StringOps
+ *  @define coll string
  */
 final class StringOps(override val repr: String) extends StringLike[String] {
 
diff --git a/src/library/scala/collection/immutable/Traversable.scala b/src/library/scala/collection/immutable/Traversable.scala
index af7f6979c9..61a7f3ebd1 100644
--- a/src/library/scala/collection/immutable/Traversable.scala
+++ b/src/library/scala/collection/immutable/Traversable.scala
@@ -26,11 +26,9 @@ trait Traversable[+A] extends scala.collection.Traversable[A]
   override def companion: GenericCompanion[Traversable] = Traversable
 }
 
-/** A factory object for the trait <code>Traversable</code>.
- *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.8
+/** $factoryInfo
+ *  @define Coll immutable.Travesable
+ *  @define coll immutable traversable object
  */
 object Traversable extends TraversableFactory[Traversable] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Traversable[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/immutable/TreeMap.scala b/src/library/scala/collection/immutable/TreeMap.scala
index bd04b8d2e2..61cfe2e13b 100644
--- a/src/library/scala/collection/immutable/TreeMap.scala
+++ b/src/library/scala/collection/immutable/TreeMap.scala
@@ -15,22 +15,33 @@ package immutable
 import generic._
 import mutable.Builder
 
-/** The canonical factory of <a href="TreeMap.html">TreeMap</a>'s.
- *
- *  @since 1
+/** $factoryInfo
+ *  @define Coll immutable.TreeMap
+ *  @define coll immutable tree map
  */
 object TreeMap extends ImmutableSortedMapFactory[TreeMap] {
   def empty[A, B](implicit ord: Ordering[A]) = new TreeMap[A, B]()(ord)
+  /** $sortedMapCanBuildFromInfo */
   implicit def canBuildFrom[A, B](implicit ord: Ordering[A]): CanBuildFrom[Coll, (A, B), TreeMap[A, B]] = new SortedMapCanBuildFrom[A, B]
   private def make[A, B](s: Int, t: RedBlack[A]#Tree[B])(implicit ord: Ordering[A]) = new TreeMap[A, B](s, t)(ord)
 }
 
 /** This class implements immutable maps using a tree.
  *
+ *  @tparam A         the type of the keys contained in this tree map.
+ *  @tparam B         the type of the values associated with the keys.
+ *  @param ordering   the implicit ordering used to compare objects of type `A`.
+ *
  *  @author  Erik Stenman
  *  @author  Matthias Zenger
  *  @version 1.1, 03/05/2004
  *  @since   1
+ *  @define Coll immutable.TreeMap
+ *  @define coll immutable tree map
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable
 class TreeMap[A, +B](override val size: Int, t: RedBlack[A]#Tree[B])(implicit val ordering: Ordering[A])
@@ -65,18 +76,20 @@ class TreeMap[A, +B](override val size: Int, t: RedBlack[A]#Tree[B])(implicit va
    *  if key is <em>not</em> in the TreeMap, otherwise
    *  the key is updated with the new entry.
    *
-   *  @param key ...
-   *  @param value ...
-   *  @return ...
+   *  @tparam B1     type of the value of the new binding which is a supertype of `B`
+   *  @param key     the key that should be updated
+   *  @param value   the value to be associated with `key`
+   *  @return        a new $coll with the updated binding
    */
   override def updated [B1 >: B](key: A, value: B1): TreeMap[A, B1] = {
     val newsize = if (tree.lookup(key).isEmpty) size + 1 else size
     TreeMap.make(newsize, tree.update(key, value))
   }
 
-    /** Add a key/value pair to this map.
-   *  @param    kv the key/value pair
-   *  @return   A new map with the new binding added to this map
+  /** Add a key/value pair to this map.
+   *  @tparam   B1   type of the value of the new binding, a supertype of `B`
+   *  @param    kv   the key/value pair
+   *  @return        A new $coll with the new binding added to this map
    */
   override def + [B1 >: B] (kv: (A, B1)): TreeMap[A, B1] = updated(kv._1, kv._2)
 
@@ -84,15 +97,22 @@ class TreeMap[A, +B](override val size: Int, t: RedBlack[A]#Tree[B])(implicit va
    *  either the collection itself (if it is mutable), or a new collection
    *  with the added elements.
    *
+   *  @tparam B1   type of the values of the new bindings, a supertype of `B`
    *  @param elem1 the first element to add.
    *  @param elem2 the second element to add.
    *  @param elems the remaining elements to add.
+   *  @return      a new $coll with the updated bindings
    */
   override def + [B1 >: B] (elem1: (A, B1), elem2: (A, B1), elems: (A, B1) *): TreeMap[A, B1] =
     this + elem1 + elem2 ++ elems
 
   /** A new TreeMap with the entry added is returned,
    *  assuming that key is <em>not</em> in the TreeMap.
+   *
+   *  @tparam B1    type of the values of the new bindings, a supertype of `B`
+   *  @param key    the key to be inserted
+   *  @param value  the value to be associated with `key`
+   *  @return       a new $coll with the inserted binding, if it wasn't present in the map
    */
   def insert [B1 >: B](key: A, value: B1): TreeMap[A, B1] = {
     assert(tree.lookup(key).isEmpty)
@@ -103,11 +123,11 @@ class TreeMap[A, +B](override val size: Int, t: RedBlack[A]#Tree[B])(implicit va
     if (tree.lookup(key).isEmpty) this
     else TreeMap.make(size - 1, tree.delete(key))
 
-  /** Check if this map maps <code>key</code> to a value and return the
+  /** Check if this map maps `key` to a value and return the
    *  value if it exists.
    *
    *  @param  key     the key of the mapping of interest
-   *  @return the value of the mapping, if it exists
+   *  @return         the value of the mapping, if it exists
    */
   override def get(key: A): Option[B] = tree.lookup(key) match {
     case n: NonEmpty[b] => Some(n.value)
diff --git a/src/library/scala/collection/immutable/TreeSet.scala b/src/library/scala/collection/immutable/TreeSet.scala
index 79e1a6b00b..7b1f71df5b 100644
--- a/src/library/scala/collection/immutable/TreeSet.scala
+++ b/src/library/scala/collection/immutable/TreeSet.scala
@@ -15,11 +15,11 @@ package immutable
 import generic._
 import mutable.{Builder, AddingBuilder}
 
-/** The canonical factory of <a href="TreeSet.html">TreeSet</a>'s.
- *
- *  @since 1
+/** $factoryInfo
+ *  @define Coll immutable.TreeSet
+ *  @define coll immutable tree set
  */
-object TreeSet extends SortedSetFactory[TreeSet] {
+object TreeSet extends ImmutableSortedSetFactory[TreeSet] {
   implicit def implicitBuilder[A](implicit ordering: Ordering[A]): Builder[A, TreeSet[A]] = newBuilder[A](ordering)
   override def newBuilder[A](implicit ordering: Ordering[A]): Builder[A, TreeSet[A]] =
     new AddingBuilder(empty[A](ordering))
@@ -31,9 +31,18 @@ object TreeSet extends SortedSetFactory[TreeSet] {
 
 /** This class implements immutable sets using a tree.
  *
+ *  @tparam A         the type of the elements contained in this tree set
+ *  @param ordering   the implicit ordering used to compare objects of type `A`
+ *
  *  @author  Martin Odersky
  *  @version 2.0, 02/01/2007
  *  @since   1
+ *  @define Coll immutable.TreeSet
+ *  @define coll immutable tree set
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(-234066569443569402L)
 class TreeSet[A](override val size: Int, t: RedBlack[A]#Tree[Unit])
@@ -54,29 +63,40 @@ class TreeSet[A](override val size: Int, t: RedBlack[A]#Tree[Unit])
    */
   override def empty = TreeSet.empty
 
-  /** A new TreeSet with the entry added is returned,
+  /** Creates a new `TreeSet` with the entry added.
+   *
+   *  @param elem    a new element to add.
+   *  @return        a new $coll containing `elem` and all the elements of this $coll.
    */
   def + (elem: A): TreeSet[A] = {
     val newsize = if (tree.lookup(elem).isEmpty) size + 1 else size
     newSet(newsize, tree.update(elem, ()))
   }
 
-  /** A new TreeSet with the entry added is returned,
+  /** A new `TreeSet` with the entry added is returned,
    *  assuming that elem is <em>not</em> in the TreeSet.
+   *
+   *  @param elem    a new element to add.
+   *  @return        a new $coll containing `elem` and all the elements of this $coll.
    */
   def insert(elem: A): TreeSet[A] = {
     assert(tree.lookup(elem).isEmpty)
     newSet(size + 1, tree.update(elem, ()))
   }
 
+  /** Creates a new `TreeSet` with the entry removed.
+   *
+   *  @param elem    a new element to add.
+   *  @return        a new $coll containing all the elements of this $coll except `elem`.
+   */
   def - (elem:A): TreeSet[A] =
     if (tree.lookup(elem).isEmpty) this
     else newSet(size - 1, tree delete elem)
 
-  /** Checks if this set contains element <code>elem</code>.
+  /** Checks if this set contains element `elem`.
    *
    *  @param  elem    the element to check for membership.
-   *  @return true, iff <code>elem</code> is contained in this set.
+   *  @return true, iff `elem` is contained in this set.
    */
   def contains(elem: A): Boolean = !tree.lookup(elem).isEmpty
 
diff --git a/src/library/scala/collection/immutable/WrappedString.scala b/src/library/scala/collection/immutable/WrappedString.scala
index cefbd96b5c..011774e10d 100644
--- a/src/library/scala/collection/immutable/WrappedString.scala
+++ b/src/library/scala/collection/immutable/WrappedString.scala
@@ -17,14 +17,18 @@ import mutable.{Builder, StringBuilder}
 import scala.util.matching.Regex
 
 /**
- * This class serves as a wrapper augmenting `String`s with all the operations
- * found in indexed sequences.
+ *  This class serves as a wrapper augmenting `String`s with all the operations
+ *  found in indexed sequences.
  *
- * The difference between this class and `StringOps` is that calling transformer
- * methods such as `filter` and `map` will yield an object of type `WrappedString`
- * rather than a `String`.
+ *  The difference between this class and `StringOps` is that calling transformer
+ *  methods such as `filter` and `map` will yield an object of type `WrappedString`
+ *  rather than a `String`.
  *
- * @since 2.8
+ *  @param self    a string contained within this wrapped string
+ *
+ *  @since 2.8
+ *  @define Coll WrappedString
+ *  @define coll wrapped string
  */
 class WrappedString(override val self: String) extends IndexedSeq[Char] with StringLike[WrappedString] with Proxy {
 
@@ -38,8 +42,9 @@ class WrappedString(override val self: String) extends IndexedSeq[Char] with Str
     new WrappedString(self.substring(from max 0, until min self.length))
 }
 
-/**
- * @since 2.8
+/** A companion object for wrapped strings.
+ *
+ *  @since 2.8
  */
 object WrappedString {
   def newBuilder: Builder[Char, WrappedString] = new StringBuilder() mapResult (new WrappedString(_))