Immutable up to Queue docs. no review

18 files changed, 133 insertions, 111 deletions

diff --git a/src/library/scala/collection/BitSetLike.scala b/src/library/scala/collection/BitSetLike.scala
index 7c5e2fb269..3028cca6eb 100644
--- a/src/library/scala/collection/BitSetLike.scala
+++ b/src/library/scala/collection/BitSetLike.scala
@@ -41,7 +41,7 @@ trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, T
   protected def nwords: Int
 
   /** The words at index `idx', or 0L if outside the range of the set
-   *  @note Requires `idx >= 0`
+   *  '''Note:''' requires `idx >= 0`
    */
   protected def word(idx: Int): Long
 
diff --git a/src/library/scala/collection/IndexedSeqLike.scala b/src/library/scala/collection/IndexedSeqLike.scala
index 453b4384f7..7bfad167c6 100644
--- a/src/library/scala/collection/IndexedSeqLike.scala
+++ b/src/library/scala/collection/IndexedSeqLike.scala
@@ -66,13 +66,13 @@ trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
       if (i < end) self(i) else Iterator.empty.next
 
     /** $super
-     *  @note `drop` is overridden to enable fast searching in the middle of indexed sequences.
+     *  '''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
 
     /** $super
-     *  @note `take` is overridden to be symmetric to `drop`.
+     *  '''Note:''' `take` is overridden to be symmetric to `drop`.
      */
     override def take(n: Int): Iterator[A] =
       if (n <= 0) Iterator.empty.buffered
diff --git a/src/library/scala/collection/Iterator.scala b/src/library/scala/collection/Iterator.scala
index 2ee4e8056e..24c447b24b 100644
--- a/src/library/scala/collection/Iterator.scala
+++ b/src/library/scala/collection/Iterator.scala
@@ -32,10 +32,10 @@ object Iterator {
   }
 
   /** Creates an iterator which produces a single element.
+   *  '''Note:''' Equivalent, but more efficient than Iterator(elem)
    *  @param elem the element
    *  @return An iterator which produces `elem` on the first call to `next`,
    *          and which has no further elements.
-   *  @note  Equivalent, but more efficient than Iterator(elem)
    */
   def single[A](elem: A) = new Iterator[A] {
     private var hasnext = true
@@ -429,7 +429,7 @@ trait Iterator[+A] extends TraversableOnce[A] {
    *  satisfy the predicate `p`. The order of the elements
    *  is preserved.
    *
-   *  @note `withFilter` is the same as `filter` on iterators. It exists so that
+   *  '''Note:''' `withFilter` is the same as `filter` on iterators. It exists so that
    *  for-expressions with filters work over iterators.
    *
    *  @param p the predicate used to test values.
@@ -1033,10 +1033,10 @@ trait Iterator[+A] extends TraversableOnce[A] {
    *  this sequence starting at position `start`.  Like `copyToArray`,
    *  but designed to accomodate IO stream operations.
    *
+   *  '''Note:'''   the array must be large enough to hold `sz` elements.
    *  @param  xs    the array to fill.
    *  @param  start the starting index.
    *  @param  sz    the maximum number of elements to be read.
-   *  @note          the array must be large enough to hold `sz` elements.
    */
   @deprecated("use copyToArray instead")
   def readInto[B >: A](xs: Array[B], start: Int, sz: Int) {
diff --git a/src/library/scala/collection/Map.scala b/src/library/scala/collection/Map.scala
index 9d44a950de..0722d55f03 100644
--- a/src/library/scala/collection/Map.scala
+++ b/src/library/scala/collection/Map.scala
@@ -13,43 +13,33 @@ package scala.collection
 
 import generic._
 
-/** <p>
- *    A map from keys of type <code>A</code> to values of type <code>B</code>.
- *    To implement a concrete map, you need to provide implementations of the
- *    following methods (where <code>This</code> is the type of the map in question):
- *  </p><pre>
- *    <b>def</b> get(key: A): Option[B]
- *    <b>def</b> iterator: Iterator[(A, B)]
- *    <b>def</b> + [B1 >: B](kv: (A, B1)): This
- *    <b>def</b> -(key: A): This</pre>
- *  <p>
- *    If you wish that methods like `take`, `drop`, `filter` return the same kind
- *    of map, you should also override:
- *  </p><pre>
- *    <b>def</b> empty: This</pre>
- *  <p>
- *    It might also be a good idea to override methods <code>foreach</code>
- *    and <code>size</code> for efficiency.
- *  </p>
+/**
+ *  A map from keys of type `A` to values of type `B`.
  *
- * @note If you do not have specific implementations for `add` and `-` in mind,
- *       you might consider inheriting from <code>DefaultMap</code> instead.
+ *  $mapnote
  *
- * @note If your additions and mutations return the same kind of map as the map
- *       you are defining, you should inherit from <code>MapLike</code> as well.
+ *  '''Note:''' If you do not have specific implementations for `add` and `-` in mind,
+ *        you might consider inheriting from `DefaultMap` instead.
  *
- * @since 1
+ *  '''Note:''' If your additions and mutations return the same kind of map as the map
+ *        you are defining, you should inherit from `MapLike` as well.
+ *
+ *  @tparam A     the type of the keys in this map.
+ *  @tparam B     the type of the values associated with keys.
+ *
+ *  @since 1
  */
 trait Map[A, +B] extends Iterable[(A, B)] with MapLike[A, B, Map[A, B]] {
   def empty: Map[A, B] = Map.empty
 }
 
-/* Factory object for `Map` class
- *
- * @since 2.5
+/** $factoryInfo
+ *  @define Coll Map
+ *  @define coll map
  */
 object Map extends MapFactory[Map] {
   def empty[A, B]: immutable.Map[A, B] = immutable.Map.empty
 
+  /** $mapCanBuildFromInfo */
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), Map[A, B]] = new MapCanBuildFrom[A, B]
 }
diff --git a/src/library/scala/collection/MapLike.scala b/src/library/scala/collection/MapLike.scala
index 057224a705..efbf9227d8 100644
--- a/src/library/scala/collection/MapLike.scala
+++ b/src/library/scala/collection/MapLike.scala
@@ -18,17 +18,18 @@ import PartialFunction._
 /** A template trait for maps of type `Map[A, B]` which associate keys of type `A`
  *  with values of type `B`.
  *
+ *  $mapnote
+ *
  *  @tparam A    the type of the keys.
  *  @tparam B    the type of associated values.
  *  @tparam This the type of the map itself.
  *
- *  $mapnote
  *
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since   2.8
- *  $mapnote
- *  @define $mapnote  @note
+ *  @define $mapnote
+ *    '''Note:'''
  *    This trait provides most of the operations of a `Map` independently of its representation.
  *    It is typically inherited by concrete implementations of maps.
  *
@@ -287,14 +288,15 @@ self =>
     ((repr: Map[A, B1]) /: xs) (_ + _)
 
   /** Returns a new map with all key/value pairs for which the predicate
-   *  <code>p</code> returns <code>true</code>.
+   *  `p` returns `true`.
    *
-   *  @param p A predicate over key-value pairs
-   *  @note    This method works by successively removing elements fro which the
+   *  '''Note:'''    This method works by successively removing elements fro which the
    *           predicate is false from this set.
    *           If removal is slow, or you expect that most elements of the set
-   *           will be removed, you might consider using <code>filter</code>
+   *           will be removed, you might consider using `filter`
    *           with a negated predicate instead.
+   *  @param p    A predicate over key-value pairs
+   *  @return     A new map containing elements not satisfying the predicate.
    */
   override def filterNot(p: ((A, B)) => Boolean): This = {
     var res: This = repr
diff --git a/src/library/scala/collection/SetLike.scala b/src/library/scala/collection/SetLike.scala
index 44dac8e8fe..15e3ef43ca 100644
--- a/src/library/scala/collection/SetLike.scala
+++ b/src/library/scala/collection/SetLike.scala
@@ -113,10 +113,10 @@ self =>
 
   /** Computes the intersection between this set and another set.
    *
+   *  '''Note:'''  Same as `intersect`.
    *  @param   that  the set to intersect with.
    *  @return  a new set consisting of all elements that are both in this
    *  set and in the given set `that`.
-   *  @note  Same as `intersect`.
    */
   def &(that: Set[A]): This = intersect(that)
 
@@ -138,10 +138,10 @@ self =>
 
   /** Computes the union between this set and another set.
    *
+   *  '''Note:'''  Same as `union`.
    *  @param   that  the set to form the union with.
    *  @return  a new set consisting of all elements that are in this
    *  set or in the given set `that`.
-   *  @note       Same as `union`.
    */
   def | (that: Set[A]): This = union(that)
 
@@ -155,10 +155,10 @@ self =>
 
   /** The difference of this set and another set.
    *
+   *  '''Note:'''  Same as `diff`.
    *  @param that the set of elements to exclude.
    *  @return     a set containing those elements of this
    *              set that are not also contained in the given set `that`.
-   *  @note       Same as `diff`.
    */
   def &~(that: Set[A]): This = diff(that)
 
@@ -181,13 +181,13 @@ self =>
 
   /** Compares this set with another object for equality.
    *
-   *  @param that the other object
-   *  @return     `true` if `that` is a set which contains the same elements
-   *              as this set.
-   *  @note This operation contains an unchecked cast: if `that`
+   *  '''Note:''' This operation contains an unchecked cast: if `that`
    *        is a set, it will assume with an unchecked cast
    *        that it has the same element type as this set.
    *        Any subsequent ClassCastException is treated as a `false` result.
+   *  @param that the other object
+   *  @return     `true` if `that` is a set which contains the same elements
+   *              as this set.
    */
   override def equals(that: Any): Boolean = that match {
     case that: Set[_] =>
diff --git a/src/library/scala/collection/generic/GenericCompanion.scala b/src/library/scala/collection/generic/GenericCompanion.scala
index 4332a1c936..1004f4f15a 100644
--- a/src/library/scala/collection/generic/GenericCompanion.scala
+++ b/src/library/scala/collection/generic/GenericCompanion.scala
@@ -14,7 +14,7 @@ package generic
 
 import mutable.Builder
 
-/** A template class for companion objects of ``regular'' collection classes
+/** A template class for companion objects of ''regular'' collection classes
  *  represent an unconstrained higher-kinded type. Typically
  *  such classes inherit from trait `GenericTraversableTemplate`.
  *  @tparam  CC   The type constructor representing the collection class.
@@ -28,10 +28,10 @@ abstract class GenericCompanion[+CC[X] <: Traversable[X]] {
   /** The underlying collection type with unknown element type */
   type Coll = CC[_]
 
-  /** The default builder for $Coll objects. */
+  /** The default builder for `$Coll` objects. */
   def newBuilder[A]: Builder[A, CC[A]]
 
-  /** The empty collection of type $Coll[A] */
+  /** The empty collection of type `$Coll[A]` */
   def empty[A]: CC[A] = newBuilder[A].result
 
   /** Creates a $coll with the specified elements.
diff --git a/src/library/scala/collection/generic/ImmutableMapFactory.scala b/src/library/scala/collection/generic/ImmutableMapFactory.scala
index 494036467f..e61da8c1d0 100644
--- a/src/library/scala/collection/generic/ImmutableMapFactory.scala
+++ b/src/library/scala/collection/generic/ImmutableMapFactory.scala
@@ -21,5 +21,7 @@ package generic
  *    This object provides a set of operations needed to create immutable maps of type `$Coll`.
  *    @author Martin Odersky
  *    @version 2.8
+ *  @define mapCanBuildFromInfo
+ *    The standard `CanBuildFrom` instance for maps.
  */
 abstract class ImmutableMapFactory[CC[A, +B] <: immutable.Map[A, B] with immutable.MapLike[A, B, CC[A, B]]] extends MapFactory[CC]
diff --git a/src/library/scala/collection/immutable/HashMap.scala b/src/library/scala/collection/immutable/HashMap.scala
index ae438d0d09..b82e50ec06 100644
--- a/src/library/scala/collection/immutable/HashMap.scala
+++ b/src/library/scala/collection/immutable/HashMap.scala
@@ -17,7 +17,7 @@ import annotation.unchecked.uncheckedVariance
 
 /** This class implements immutable maps using a hash trie.
  *
- *  <b>Note:</b> the builder of a hash map returns specialized representations EmptyMap,Map1,..., Map4
+ *  '''Note:''' the builder of a hash map returns specialized representations EmptyMap,Map1,..., Map4
  *  for maps of size <= 4.
  *
  *  @tparam A      the type of the keys contained in this hash map.
@@ -90,6 +90,7 @@ class HashMap[A, +B] extends Map[A,B] with MapLike[A, B, HashMap[A, B]] {
  *  @since   2.3
  */
 object HashMap extends ImmutableMapFactory[HashMap] {
+  /** $mapCanBuildFromInfo */
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), HashMap[A, B]] = new MapCanBuildFrom[A, B]
   def empty[A, B]: HashMap[A, B] = EmptyHashMap.asInstanceOf[HashMap[A, B]]
 
diff --git a/src/library/scala/collection/immutable/HashSet.scala b/src/library/scala/collection/immutable/HashSet.scala
index 942c3f1814..68da0cef50 100644
--- a/src/library/scala/collection/immutable/HashSet.scala
+++ b/src/library/scala/collection/immutable/HashSet.scala
@@ -17,7 +17,7 @@ import annotation.unchecked.uncheckedVariance
 
 /** This class implements immutable sets using a hash trie.
  *
- *  <b>Note:</b> the builder of a hash set returns specialized representations `EmptySet`,`Set1`,..., `Set4`
+ *  '''Note:''' the builder of a hash set returns specialized representations `EmptySet`,`Set1`,..., `Set4`
  *  for sets of `size <= 4`.
  *
  *  @tparam A      the type of the elements contained in this hash set.
diff --git a/src/library/scala/collection/immutable/ListMap.scala b/src/library/scala/collection/immutable/ListMap.scala
index 13d5bbe2ac..a88c3a52d5 100644
--- a/src/library/scala/collection/immutable/ListMap.scala
+++ b/src/library/scala/collection/immutable/ListMap.scala
@@ -20,6 +20,7 @@ import generic._
  *  @define coll immutable list map
  */
 object ListMap extends ImmutableMapFactory[ListMap] {
+  /** $mapCanBuildFromInfo */
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), ListMap[A, B]] =
     new MapCanBuildFrom[A, B]
   def empty[A, B]: ListMap[A, B] = new ListMap
diff --git a/src/library/scala/collection/immutable/Map.scala b/src/library/scala/collection/immutable/Map.scala
index e3469099b8..74cf4a1715 100644
--- a/src/library/scala/collection/immutable/Map.scala
+++ b/src/library/scala/collection/immutable/Map.scala
@@ -48,12 +48,13 @@ trait Map[A, +B] extends Iterable[(A, B)]
   def withDefaultValue[B1 >: B](d: B1): Map[A, B1] = new Map.WithDefault[A, B1](this, x => d)
 }
 
-/**
- * A companion object for immutable maps.
- *
- * @since 1
+/** $factoryInfo
+ *  @define Coll immutable.Map
+ *  @define coll immutable map
  */
 object Map extends ImmutableMapFactory[Map] {
+
+  /** $mapCanBuildFromInfo */
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), Map[A, B]] = new MapCanBuildFrom[A, B]
 
   def empty[A, B]: Map[A, B] = EmptyMap.asInstanceOf[Map[A, B]]
diff --git a/src/library/scala/collection/immutable/MapLike.scala b/src/library/scala/collection/immutable/MapLike.scala
index 6f816ffa52..367ffadd43 100644
--- a/src/library/scala/collection/immutable/MapLike.scala
+++ b/src/library/scala/collection/immutable/MapLike.scala
@@ -14,32 +14,38 @@ package immutable
 
 import generic._
 
-/** <p>
- *    A generic template for immutable maps from keys of type <code>A</code>
- *    to values of type <code>B</code>.<br/>
- *    To implement a concrete map, you need to provide implementations of the
- *    following methods (where <code>This</code> is the type of the map in
- *    question):
- *  </p>
- *  <pre>
- *    <b>def</b> get(key: A): Option[B]
- *    <b>def</b> iterator: Iterator[(A, B)]
- *    <b>def</b> + [B1 >: B](kv: (A, B)): Map[A, B1]
- *    <b>def</b> - (key: A): This</pre>
- *  <p>
- *    If you wish that methods <code>like</code>, <code>take</code>, <code>drop</code>,
- *    <code>filter</code> return the same kind of map, you should also override:
- *  </p>
- *  <pre>
- *    <b>def</b> empty: This</pre>
- *  <p>
- *    It is also good idea to override methods <code>foreach</code> and
- *    <code>size</code> for efficiency.
- *  </p>
+/**
+ *  A generic template for immutable maps from keys of type `A`
+ *  to values of type `B`.
+ *  To implement a concrete map, you need to provide implementations of the
+ *  following methods (where `This` is the type of the actual map implementation):
+ *
+ *  {{{
+ *    def get(key: A): Option[B]
+ *    def iterator: Iterator[(A, B)]
+ *    def + [B1 >: B](kv: (A, B)): Map[A, B1]
+ *    def - (key: A): This
+ *  }}}
+ *
+ *  If you wish that transformer methods like `take`, `drop`, `filter` return the
+ *  same kind of map, you should also override:
+ *
+ *  {{{
+ *    def empty: This
+ *  }}}
+ *
+ *  It is also good idea to override methods `foreach` and
+ *  `size` for efficiency.
+ *
+ *  @param A     the type of the keys contained in this collection.
+ *  @param B     the type of the values associated with the keys.
+ *  @param This  The type of the actual map implementation.
  *
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since   2.8
+ *  @define Coll immutable.Map
+ *  @define coll immutable map
  */
 trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, B]]
   extends scala.collection.MapLike[A, B, This]
@@ -55,8 +61,8 @@ trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, B]]
   override def updated [B1 >: B](key: A, value: B1): immutable.Map[A, B1] = this + ((key, value))
 
   /** Add a key/value pair to this map, returning a new map.
-   *  @param    kv the key/value pair
-   *  @return   A new map with the new binding added to this map
+   *  @param    kv the key/value pair.
+   *  @return   A new map with the new binding added to this map.
    */
   def + [B1 >: B] (kv: (A, B1)): immutable.Map[A, B1]
 
@@ -66,6 +72,7 @@ trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, 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 map with the new bindings added to this map.
    */
   override def + [B1 >: B] (elem1: (A, B1), elem2: (A, B1), elems: (A, B1) *): immutable.Map[A, B1] =
     this + elem1 + elem2 ++ elems
@@ -73,7 +80,8 @@ trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, B]]
   /** Adds a number of elements provided by a traversable object
    *  and returns a new collection with the added elements.
    *
-   *  @param elems     the traversable object.
+   *  @param xs      the traversable object consisting of key-value pairs.
+   *  @return        a new immutable map with the bindings of this map and those from `xs`.
    */
   override def ++[B1 >: B](xs: TraversableOnce[(A, B1)]): immutable.Map[A, B1] =
     ((repr: immutable.Map[A, B1]) /: xs) (_ + _)
@@ -104,7 +112,7 @@ trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, B]]
   }
 
   /** This function transforms all the values of mappings contained
-   *  in this map with function <code>f</code>.
+   *  in this map with function `f`.
    *
    *  @param f A function over keys and values
    *  @return  the updated map
diff --git a/src/library/scala/collection/immutable/MapProxy.scala b/src/library/scala/collection/immutable/MapProxy.scala
index 371af042e7..a511c6d145 100644
--- a/src/library/scala/collection/immutable/MapProxy.scala
+++ b/src/library/scala/collection/immutable/MapProxy.scala
@@ -12,14 +12,12 @@
 package scala.collection
 package immutable
 
-/** <p>
- *    This is a simple wrapper class for <a href="Map.html"
- *    target="contentFrame"><code>scala.collection.mutable.Map</code></a>.
- *  </p>
- *  <p>
- *    It is most useful for assembling customized map abstractions
- *    dynamically using object composition and forwarding.
- *  </p>
+/**
+ *  This is a simple wrapper class for <a href="Map.html"
+ *  target="contentFrame">`scala.collection.immutable.Map`</a>.
+ *
+ *  It is most useful for assembling customized map abstractions
+ *  dynamically using object composition and forwarding.
  *
  *  @author  Matthias Zenger, Martin Odersky
  *  @version 2.0, 31/12/2006
diff --git a/src/library/scala/collection/immutable/NumericRange.scala b/src/library/scala/collection/immutable/NumericRange.scala
index 645c5fed24..67115f7184 100644
--- a/src/library/scala/collection/immutable/NumericRange.scala
+++ b/src/library/scala/collection/immutable/NumericRange.scala
@@ -14,24 +14,28 @@ package immutable
 import mutable.{ Builder, ListBuffer }
 import generic._
 
-/** <p>
- *    <code>NumericRange</code> is a more generic version of the
- *    <code>Range</code> class which works with arbitrary types.
- *    It must be supplied with an `Integral` implementation of the
- *    range type.
+/** `NumericRange` is a more generic version of the
+ *  `Range` class which works with arbitrary types.
+ *  It must be supplied with an `Integral` implementation of the
+ *  range type.
  *
- *    Factories for likely types include `Range.BigInt`, `Range.Long`,
- *    and `Range.BigDecimal`.  `Range.Int` exists for completeness, but
- *    the `Int`-based `scala.Range` should be more performant.
- *  </p><pre>
- *     <b>val</b> r1 = new Range(0, 100, 1)
- *     <b>val</b> veryBig = Int.MaxValue.toLong + 1
- *     <b>val</b> r2 = Range.Long(veryBig, veryBig + 100, 1)
+ *  Factories for likely types include `Range.BigInt`, `Range.Long`,
+ *  and `Range.BigDecimal`.  `Range.Int` exists for completeness, but
+ *  the `Int`-based `scala.Range` should be more performant.
+ *
+ *  {{{
+ *     val r1 = new Range(0, 100, 1)
+ *     val veryBig = Int.MaxValue.toLong + 1
+ *     val r2 = Range.Long(veryBig, veryBig + 100, 1)
  *     assert(r1 sameElements r2.map(_ - veryBig))
- *  </pre>
+ *  }}}
  *
  *  @author  Paul Phillips
  *  @version 2.8
+ *  @define Coll NumericRange
+ *  @define coll numeric range
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable
 abstract class NumericRange[T]
@@ -68,7 +72,7 @@ extends IndexedSeq[T]
   protected def underlying = collection.immutable.IndexedSeq.empty[T]
 
   /** Create a new range with the start and end values of this range and
-   *  a new <code>step</code>.
+   *  a new `step`.
    */
   def by(newStep: T): NumericRange[T] = copy(start, end, newStep)
 
@@ -200,6 +204,8 @@ extends IndexedSeq[T]
   }
 }
 
+/** A companion object for numeric ranges.
+ */
 object NumericRange {
   class Inclusive[T](start: T, end: T, step: T)(implicit num: Integral[T])
   extends NumericRange(start, end, step, true) {
diff --git a/src/library/scala/collection/immutable/PagedSeq.scala b/src/library/scala/collection/immutable/PagedSeq.scala
index bd12502520..2a1b3c110c 100644
--- a/src/library/scala/collection/immutable/PagedSeq.scala
+++ b/src/library/scala/collection/immutable/PagedSeq.scala
@@ -15,7 +15,7 @@ package immutable
 import java.io._
 import scala.util.matching.Regex
 
-/** The PagedSeq object defines a lazy implementations of
+/** The `PagedSeq` object defines a lazy implementations of
  *  a random access sequence.
  *
  *  @since 2.7
@@ -108,8 +108,14 @@ import PagedSeq._
 /** An implementation of lazily computed sequences, where elements are stored
  *  in ``pages'', i.e. arrays of fixed size.
  *
- * @author Martin Odersky
- * @since  2.7
+ *  @tparam T     the type of the elements contained in this paged sequence, with a `ClassManifest` context bound.
+ *
+ *  @author Martin Odersky
+ *  @since  2.7
+ *  @define Coll PagedSeq
+ *  @define coll paged sequence
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 class PagedSeq[T: ClassManifest] protected(
   more: (Array[T], Int, Int) => Int,
diff --git a/src/library/scala/collection/immutable/Queue.scala b/src/library/scala/collection/immutable/Queue.scala
index 02d344ceea..575d84c878 100644
--- a/src/library/scala/collection/immutable/Queue.scala
+++ b/src/library/scala/collection/immutable/Queue.scala
@@ -15,12 +15,14 @@ package immutable
 import generic._
 import mutable.{ Builder, ListBuffer }
 
-/** <code>Queue</code> objects implement data structures that allow to
+/** `Queue` objects implement data structures that allow to
  *  insert and retrieve elements in a first-in-first-out (FIFO) manner.
  *
  *  @author  Erik Stenman
  *  @version 1.0, 08/07/2003
  *  @since   1
+ *  @define Coll immutable.Queue
+ *  @define coll immutable queue
  */
 @serializable
 @SerialVersionUID(-7622936493364270175L)
@@ -31,11 +33,11 @@ class Queue[+A] protected(protected val in: List[A], protected val out: List[A])
 
   override def companion: GenericCompanion[Queue] = Queue
 
-  /** Returns the <code>n</code>-th element of this queue.
+  /** Returns the `n`-th element of this queue.
    *  The first element is at position 0.
    *
    *  @param  n index of the element to return
-   *  @return   the element at position <code>n</code> in this queue.
+   *  @return   the element at position `n` in this queue.
    *  @throws Predef.NoSuchElementException if the queue is too short.
    */
   def apply(n: Int): A = {
@@ -127,7 +129,12 @@ class Queue[+A] protected(protected val in: List[A], protected val out: List[A])
   override def toString() = mkString("Queue(", ", ", ")")
 }
 
+/** $factoryInfo
+ *  @define Coll immutable.Queue
+ *  @define coll immutable queue
+ */
 object Queue extends SeqFactory[Queue] {
+  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Queue[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, Queue[A]] = new ListBuffer[A] mapResult (x => new Queue[A](Nil, x.toList))
   override def empty[A]: Queue[A] = new Queue[A](Nil, Nil)
diff --git a/src/library/scala/collection/mutable/Queue.scala b/src/library/scala/collection/mutable/Queue.scala
index ef5583ab23..3132e2f422 100644
--- a/src/library/scala/collection/mutable/Queue.scala
+++ b/src/library/scala/collection/mutable/Queue.scala
@@ -22,8 +22,8 @@ import generic._
  *  @version 2.8
  *  @since   1
  *
- *  @define Coll Queue
- *  @define coll queue
+ *  @define Coll mutable.Queue
+ *  @define coll mutable queue
  *  @define orderDependent
  *  @define orderDependentFold
  *  @define mayNotTerminateInf