Docs. no review

12 files changed, 144 insertions, 50 deletions

diff --git a/src/library/scala/collection/generic/ImmutableMapFactory.scala b/src/library/scala/collection/generic/ImmutableMapFactory.scala
index e61da8c1d0..6096a3184d 100644
--- a/src/library/scala/collection/generic/ImmutableMapFactory.scala
+++ b/src/library/scala/collection/generic/ImmutableMapFactory.scala
@@ -11,14 +11,14 @@
 package scala.collection
 package generic
 
-/** A template for companion objects of `immutable.Map` and
+/** A template for companion objects of `Map` and
  *  subclasses thereof.
  *
  *  @since 2.8
- *  @define Coll immutable.Map
- *  @define coll immutable map
+ *  @define Coll Map
+ *  @define coll map
  *  @define factoryInfo
- *    This object provides a set of operations needed to create immutable maps of type `$Coll`.
+ *    This object provides a set of operations needed to create maps of type `$Coll`.
  *    @author Martin Odersky
  *    @version 2.8
  *  @define mapCanBuildFromInfo
diff --git a/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala b/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala
index d5c372ba74..d30f57f0ce 100644
--- a/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala
+++ b/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala
@@ -12,8 +12,16 @@
 package scala.collection
 package generic
 
-/** A template for companion objects of immutable.Map and subclasses thereof.
+/** A template for companion objects of `SortedMap` and subclasses thereof.
  *
  *  @since 2.8
+ *  @define Coll SortedMap
+ *  @define coll sorted map
+ *  @define factoryInfo
+ *    This object provides a set of operations needed to create sorted maps of type `$Coll`.
+ *    @author Martin Odersky
+ *    @version 2.8
+ *  @define sortedMapCanBuildFromInfo
+ *    The standard `CanBuildFrom` instance for sorted maps
  */
 abstract class ImmutableSortedMapFactory[CC[A, B] <: immutable.SortedMap[A, B] with SortedMapLike[A, B, CC[A, B]]] extends SortedMapFactory[CC]
diff --git a/src/library/scala/collection/generic/ImmutableSortedSetFactory.scala b/src/library/scala/collection/generic/ImmutableSortedSetFactory.scala
index df5c2c7959..684e7c41f1 100644
--- a/src/library/scala/collection/generic/ImmutableSortedSetFactory.scala
+++ b/src/library/scala/collection/generic/ImmutableSortedSetFactory.scala
@@ -12,8 +12,16 @@
 package scala.collection
 package generic
 
-/** A template for companion objects of mutable.Map and subclasses thereof.
+/** A template for companion objects of `SortedSet` and subclasses thereof.
  *
  *  @since 2.8
+ *  @define Coll immutable.SortedSet
+ *  @define coll immutable sorted
+ *  @define factoryInfo
+ *    This object provides a set of operations needed to create sorted sets of type `$Coll`.
+ *    @author Martin Odersky
+ *    @version 2.8
+ *  @define sortedSetCanBuildFromInfo
+ *    The standard `CanBuildFrom` instance for sorted sets
  */
 abstract class ImmutableSortedSetFactory[CC[A] <: immutable.SortedSet[A] with SortedSetLike[A, CC[A]]] extends SortedSetFactory[CC]
\ No newline at end of file
diff --git a/src/library/scala/collection/immutable/Queue.scala b/src/library/scala/collection/immutable/Queue.scala
index 575d84c878..7a903cb201 100644
--- a/src/library/scala/collection/immutable/Queue.scala
+++ b/src/library/scala/collection/immutable/Queue.scala
@@ -23,6 +23,8 @@ import mutable.{ Builder, ListBuffer }
  *  @since   1
  *  @define Coll immutable.Queue
  *  @define coll immutable queue
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable
 @SerialVersionUID(-7622936493364270175L)
diff --git a/src/library/scala/collection/immutable/Range.scala b/src/library/scala/collection/immutable/Range.scala
index 5424a7afcb..8f1f7d58a6 100644
--- a/src/library/scala/collection/immutable/Range.scala
+++ b/src/library/scala/collection/immutable/Range.scala
@@ -10,20 +10,31 @@
 
 package scala.collection.immutable
 
-/** <p>
- *    The <code>Range</code> class represents integer values in range
- *    <code>[start;end)</code> with non-zero step value <code>step</code>.
- *    It's a special case of an indexed sequence.
- *    For example:
- *  </p><pre>
- *     <b>val</b> r1 = 0 until 10
- *     <b>val</b> r2 = r1.start until r1.end by r1.step + 1
+/** The `Range` class represents integer values in range
+ *  ''[start;end)'' with non-zero step value `step`.
+ *  It's a special case of an indexed sequence.
+ *  For example:
+ *
+ *  {{{
+ *     val r1 = 0 until 10
+ *     val r2 = r1.start until r1.end by r1.step + 1
  *     println(r2.length) // = 5
- *  </pre>
+ *  }}}
+ *
+ *  @param start      the start of this range.
+ *  @param end        the exclusive end of the range.
+ *  @param step       the step for the range.
  *
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.5
+ *  @define Coll Range
+ *  @define coll range
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
+ *  @define doesNotUseBuilders
+ *    '''Note:''' this method does not use builders to construct a new range,
+ *         and its complexity is O(1).
  */
 @serializable @SerialVersionUID(7618862778670199309L)
 class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int] {
@@ -33,7 +44,9 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int]
   protected def copy(start: Int, end: Int, step: Int): Range = new Range(start, end, step)
 
   /** Create a new range with the `start` and `end` values of this range and
-   *  a new <code>step</code>.
+   *  a new `step`.
+   *
+   *  @return a new range with a different step
    */
   def by(step: Int): Range = copy(start, end, step)
 
@@ -84,18 +97,46 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int]
     start
   }
 
+  /** Creates a new range containing the first `n` elements of this range.
+   *
+   *  $doesNotUseBuilders
+   *
+   *  @param n  the number of elements to take.
+   *  @return   a new range consisting of `n` first elements.
+   */
   final override def take(n: Int): Range = if (n > 0 && length > 0) {
     Range(start, locationAfterN(n - 1), step).inclusive
   } else {
     Range(start, start, step)
   }
 
+  /** Creates a new range containing all the elements of this range except the first `n` elements.
+   *
+   *  $doesNotUseBuilders
+   *
+   *  @param n  the number of elements to drop.
+   *  @return   a new range consisting of all the elements of this range except `n` first elements.
+   */
   final override def drop(n: Int): Range =
     copy(locationAfterN(n), end, step)
 
+  /** Creates a new range containing all the elements of this range except the last one.
+   *
+   *  $doesNotUseBuilders
+   *
+   *  @return  a new range consisting of all the elements of this range except the last one.
+   */
   final override def init: Range =
     take(length - 1)
 
+  /** Creates a new range contained in the specified slice of this range.
+   *
+   *  $doesNotUseBuilders
+   *
+   *  @param from   the start of the slice.
+   *  @param until  the end of the slice.
+   *  @return       a new range consisting of all the elements of this range contained in the specified slice.
+   */
   final override def slice(from: Int, until: Int): Range =
     drop(from).take(until - from)
 
@@ -117,12 +158,29 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int]
     (Range(start, split, step), copy(split, end, step))
   }
 
+  /** Creates a pair of new ranges, first consisting of elements before `n`, and the second
+   *  of elements after `n`.
+   *
+   *  $doesNotUseBuilders
+   */
   final override def splitAt(n: Int) = (take(n), drop(n))
 
+  /** Creates a new range consisting of the `length - n` last elements of the range.
+   *
+   *  $doesNotUseBuilders
+   */
   final override def takeRight(n: Int): Range = drop(length - n)
 
+  /** Creates a new range consisting of the initial `length - n` elements of the range.
+   *
+   *  $doesNotUseBuilders
+   */
   final override def dropRight(n: Int): Range = take(length - n)
 
+  /** Returns the reverse of this range.
+   *
+   *  $doesNotUseBuilders
+   */
   final override def reverse: Range = if (length > 0) new Range.Inclusive(last, start, -step) else this
 
   /** Make range inclusive.
@@ -156,6 +214,8 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int]
   }
 }
 
+/** A companion object for the `Range` class.
+ */
 object Range {
   private[immutable] val MAX_PRINT = 512  // some arbitrary value
 
diff --git a/src/library/scala/collection/immutable/RedBlack.scala b/src/library/scala/collection/immutable/RedBlack.scala
index ffa6194838..98a7d67d48 100644
--- a/src/library/scala/collection/immutable/RedBlack.scala
+++ b/src/library/scala/collection/immutable/RedBlack.scala
@@ -12,9 +12,9 @@
 package scala.collection
 package immutable
 
-/** A base class containing the implementations for TreeMaps and TreeSets
+/** A base class containing the implementations for `TreeMaps` and `TreeSets`.
  *
- * @since 2.3
+ *  @since 2.3
  */
 @serializable @SerialVersionUID(8691885935445612921L)
 abstract class RedBlack[A] {
diff --git a/src/library/scala/collection/immutable/Seq.scala b/src/library/scala/collection/immutable/Seq.scala
index de7804a95c..7e41ff7b94 100644
--- a/src/library/scala/collection/immutable/Seq.scala
+++ b/src/library/scala/collection/immutable/Seq.scala
@@ -19,6 +19,8 @@ import mutable.Builder
  *  that are guaranteed immutable.
  *
  *  $seqInfo
+ *  @define Coll immutable.Seq
+ *  @define coll immutable sequence
  */
 trait Seq[+A] extends Iterable[A]
                       with scala.collection.Seq[A]
@@ -27,10 +29,12 @@ trait Seq[+A] extends Iterable[A]
   override def companion: GenericCompanion[Seq] = Seq
 }
 
-/**
- * @since 2.8
+/** $factoryInfo
+ *  @define Coll immutable.Seq
+ *  @define coll immutable sequence
  */
 object Seq extends SeqFactory[Seq] {
+  /** genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Seq[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, Seq[A]] = new mutable.ListBuffer
 }
diff --git a/src/library/scala/collection/immutable/Set.scala b/src/library/scala/collection/immutable/Set.scala
index 77f16c0d14..769ee37f6b 100644
--- a/src/library/scala/collection/immutable/Set.scala
+++ b/src/library/scala/collection/immutable/Set.scala
@@ -14,23 +14,16 @@ package immutable
 
 import generic._
 
-/** <p>
- *    A generic trait for immutable sets. Concrete set implementations have
- *    to provide functionality for the abstract methods in <code>Set</code>:
- *  </p>
- *  <pre>
- *    <b>def</b> contains(elem: A): Boolean
- *    <b>def</b> iterator: Iterator[A]
- *    <b>def</b> + (elem: A): Self
- *    <b>def</b> - (elem: A): Self</pre>
- *  <p>
- *    where <code>Self</code> is the type of the set.
- *  </p>
+/** A generic trait for immutable sets.
+ *
+ *  $setnote
  *
  *  @author Matthias Zenger
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   1
+ *  @define Coll immutable.Set
+ *  @define coll immutable set
  */
 trait Set[A] extends Iterable[A]
                 with scala.collection.Set[A]
@@ -39,10 +32,12 @@ trait Set[A] extends Iterable[A]
   override def companion: GenericCompanion[Set] = Set
 }
 
-/**
- * A companion object for immutable sets.
+/** $factoryInfo
+ *  @define Coll immutable.Set
+ *  @define coll immutable set
  */
 object Set extends SetFactory[Set] {
+  /** $setCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Set[A]] = setCanBuildFrom[A]
   override def empty[A]: Set[A] = EmptySet.asInstanceOf[Set[A]]
 
diff --git a/src/library/scala/collection/immutable/SetProxy.scala b/src/library/scala/collection/immutable/SetProxy.scala
index 73c95652b3..d45b2059ff 100644
--- a/src/library/scala/collection/immutable/SetProxy.scala
+++ b/src/library/scala/collection/immutable/SetProxy.scala
@@ -12,14 +12,13 @@
 package scala.collection
 package immutable
 
-/** <p>
- *    This is a simple wrapper class for <a href="Set.html"
- *    target="contentFrame"><code>scala.collection.immutable.Set</code></a>.
- *  </p>
- *  <p>
- *    It is most useful for assembling customized set abstractions
- *    dynamically using object composition and forwarding.
- *  </p>
+/** This is a simple wrapper class for <a href="Set.html"
+ *  target="contentFrame">`scala.collection.immutable.Set`</a>.
+ *
+ *  It is most useful for assembling customized set abstractions
+ *  dynamically using object composition and forwarding.
+ *
+ *  @tparam A    type of the elements contained in this set proxy.
  *
  *  @since 2.8
  */
diff --git a/src/library/scala/collection/immutable/SortedMap.scala b/src/library/scala/collection/immutable/SortedMap.scala
index 919b529a49..243636e107 100644
--- a/src/library/scala/collection/immutable/SortedMap.scala
+++ b/src/library/scala/collection/immutable/SortedMap.scala
@@ -18,10 +18,15 @@ import annotation.unchecked.uncheckedVariance
 
 /** A map whose keys are sorted.
  *
+ *  @tparam A     the type of the keys contained in this sorted map.
+ *  @tparam B     the type of the values associated with the keys.
+ *
  *  @author Sean McDirmid
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.4
+ *  @define Coll immutable.SortedMap
+ *  @define coll immutable sorted map
  */
 trait SortedMap[A, +B] extends Map[A, B]
                          with scala.collection.SortedMap[A, B]
@@ -62,10 +67,12 @@ trait SortedMap[A, +B] extends Map[A, B]
     ((repr: SortedMap[A, B1]) /: xs) (_ + _)
 }
 
-/**
- * @since 2.4
+/** $factoryInfo
+ *  @define Coll immutable.SortedMap
+ *  @define coll immutable sorted map
  */
 object SortedMap extends ImmutableSortedMapFactory[SortedMap] {
+  /** $sortedMapCanBuildFromInfo */
   implicit def canBuildFrom[A, B](implicit ord: Ordering[A]): CanBuildFrom[Coll, (A, B), SortedMap[A, B]] = new SortedMapCanBuildFrom[A, B]
   def empty[A, B](implicit ord: Ordering[A]): SortedMap[A, B] = TreeMap.empty[A, B]
 }
diff --git a/src/library/scala/collection/immutable/SortedSet.scala b/src/library/scala/collection/immutable/SortedSet.scala
index 10ff466ff8..6c9433c30c 100644
--- a/src/library/scala/collection/immutable/SortedSet.scala
+++ b/src/library/scala/collection/immutable/SortedSet.scala
@@ -22,18 +22,20 @@ import mutable.Builder
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.4
+ *  @define Coll immutable.SortedSet
+ *  @define coll immutable sorted set
  */
 trait SortedSet[A] extends Set[A] with scala.collection.SortedSet[A] with SortedSetLike[A, SortedSet[A]] {
   /** Needs to be overridden in subclasses. */
   override def empty: SortedSet[A] = SortedSet.empty[A]
 }
 
-/**
- * A companion object for immutable sorted sets.
- *
- * @since 2.4
+/** $factoryInfo
+ *  @define Coll immutable.SortedSet
+ *  @define coll immutable sorted set
  */
 object SortedSet extends ImmutableSortedSetFactory[SortedSet] {
+  /** $sortedSetCanBuildFromInfo */
   implicit def canBuildFrom[A](implicit ord: Ordering[A]): CanBuildFrom[Coll, A, SortedSet[A]] = new SortedSetCanBuildFrom[A]
   def empty[A](implicit ord: Ordering[A]): SortedSet[A] = TreeSet.empty[A]
 }
diff --git a/src/library/scala/collection/immutable/Stack.scala b/src/library/scala/collection/immutable/Stack.scala
index 7d3c8c040b..aa7ee908d6 100644
--- a/src/library/scala/collection/immutable/Stack.scala
+++ b/src/library/scala/collection/immutable/Stack.scala
@@ -15,7 +15,12 @@ package immutable
 import generic._
 import mutable.{ ArrayBuffer, Builder }
 
+/** $factoryInfo
+ *  @define Coll immutable.Stack
+ *  @define coll immutable stack
+ */
 object Stack extends SeqFactory[Stack] {
+  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Stack[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, Stack[A]] = new ArrayBuffer[A] mapResult (buf => new Stack(buf.toList))
 
@@ -26,13 +31,17 @@ object Stack extends SeqFactory[Stack] {
 /** This class implements immutable stacks using a list-based data
  *  structure.
  *
- *  @note    This class exists only for historical reason and as an
- *           analogue of mutable stacks
+ *  '''Note:''' This class exists only for historical reason and as an
+ *           analogue of mutable stacks.
  *           Instead of an immutable stack you can just use a list.
  *
+ *  @tparam A    the type of the elements contained in this stack.
+ *
  *  @author  Matthias Zenger
  *  @version 1.0, 10/07/2003
  *  @since   1
+ *  @define Coll immutable.Stack
+ *  @define coll immutable stack
  */
 @serializable @SerialVersionUID(1976480595012942526L)
 class Stack[+A] protected (protected val elems: List[A]) extends LinearSeq[A]