docs for immutable.A-L*. no review

14 files changed, 133 insertions, 73 deletions

diff --git a/src/library/scala/collection/generic/ImmutableMapFactory.scala b/src/library/scala/collection/generic/ImmutableMapFactory.scala
index 2fd22e7f02..494036467f 100644
--- a/src/library/scala/collection/generic/ImmutableMapFactory.scala
+++ b/src/library/scala/collection/generic/ImmutableMapFactory.scala
@@ -11,9 +11,15 @@
 package scala.collection
 package generic
 
-/** A template for companion objects of <code>immutable.Map</code> and
+/** A template for companion objects of `immutable.Map` and
  *  subclasses thereof.
  *
  *  @since 2.8
+ *  @define Coll immutable.Map
+ *  @define coll immutable map
+ *  @define factoryInfo
+ *    This object provides a set of operations needed to create immutable maps of type `$Coll`.
+ *    @author Martin Odersky
+ *    @version 2.8
  */
 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/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala
index 857b537904..4c90a89104 100644
--- a/src/library/scala/collection/immutable/BitSet.scala
+++ b/src/library/scala/collection/immutable/BitSet.scala
@@ -17,6 +17,8 @@ import BitSetLike.{LogWL, updateArray}
 
 /** A class for immutable bitsets.
  *  $bitsetinfo
+ *  @define Coll immutable.BitSet
+ *  @define coll immutable bitset
  */
 @serializable @SerialVersionUID(1611436763290191562L)
 abstract class BitSet extends Set[Int]
@@ -53,12 +55,14 @@ abstract class BitSet extends Set[Int]
   }
 }
 
-/** A factory object for bitsets */
+/** $factoryInfo
+ */
 object BitSet extends BitSetFactory[BitSet] {
 
   /** The empty bitset */
   val empty: BitSet = new BitSet1(0L)
 
+  /** $bitsetCanBuildFrom */
   implicit def canBuildFrom: CanBuildFrom[BitSet, Int, BitSet] = bitsetCanBuildFrom
 
   /** A bitset containing all the bits in an array */
diff --git a/src/library/scala/collection/immutable/DefaultMap.scala b/src/library/scala/collection/immutable/DefaultMap.scala
index a19b35aff0..667d86d352 100755
--- a/src/library/scala/collection/immutable/DefaultMap.scala
+++ b/src/library/scala/collection/immutable/DefaultMap.scala
@@ -14,22 +14,24 @@ package immutable
 
 import generic._
 
-/** <p>
- *    A default map which implements the <code>updated</code> and <code>-</code>
- *    methods of maps.<br/>
- *    Instances that inherit from <code>DefaultMap[A, B]</code> still have to
- *    define:
- *  </p>
- *  <pre>
- *    <b>def</b> get(key: A): Option[B]
- *    <b>def</b> iterator: Iterator[(A, B)]</pre>
- *  <p>
- *    It refers back to the original map.
- *  </p>
- *  <p>
- *    It might also be advisable to override <code>foreach</code> or
- *    <code>size</code> if efficient implementations can be found.
- *  </p>
+/** A default map which implements the `+` and `-`
+ *  methods of maps. It does so using the default builder for
+ *  maps defined in the `Map` object.
+ *  Instances that inherit from `DefaultMap[A, B]` still have to
+ *  define:
+ *
+ *  {{{
+ *    def get(key: A): Option[B]
+ *    def iterator: Iterator[(A, B)]
+ *  }}}
+ *
+ *  It refers back to the original map.
+ *
+ *  It might also be advisable to override `foreach` or
+ *  `size` if efficient implementations can be found.
+ *
+ *  @tparam A    the type of the keys contained in this map.
+ *  @tparam B    the type of the values associated with the keys.
  *
  *  @since 2.8
  */
@@ -52,3 +54,13 @@ trait DefaultMap[A, +B] extends Map[A, B] { self =>
     b.result
   }
 }
+
+
+
+
+
+
+
+
+
+
diff --git a/src/library/scala/collection/immutable/HashMap.scala b/src/library/scala/collection/immutable/HashMap.scala
index e0f801546c..c83a5ffcb8 100644
--- a/src/library/scala/collection/immutable/HashMap.scala
+++ b/src/library/scala/collection/immutable/HashMap.scala
@@ -15,17 +15,22 @@ package immutable
 import generic._
 import annotation.unchecked.uncheckedVariance
 
-/** <p>
- *    This class implements immutable maps using a hash trie.
- *  </p>
+/** This class implements immutable maps using a hash trie.
  *
- * @note the builder of a hash map returns specialized representations EmptyMap,Map1,..., Map4
- * for maps of size <= 4.
+ *  <b>Note:</b> 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.
+ *  @tparam B      the type of the values associated with the keys.
  *
  *  @author  Martin Odersky
  *  @author  Tiark Rompf
  *  @version 2.8
  *  @since   2.3
+ *  @define Coll immutable.HashMap
+ *  @define coll immutable hash map
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(2L)
 class HashMap[A, +B] extends Map[A,B] with MapLike[A, B, HashMap[A, B]] {
@@ -76,11 +81,11 @@ class HashMap[A, +B] extends Map[A,B] with MapLike[A, B, HashMap[A, B]] {
 
 }
 
-/** A factory object for immutable HashMaps.
+/** $factoryInfo
+ *  @define Coll immutable.HashMap
+ *  @define coll immutable hash map
  *
- *  @author  Martin Odersky
  *  @author  Tiark Rompf
- *  @version 2.8
  *  @since   2.3
  */
 object HashMap extends ImmutableMapFactory[HashMap] {
diff --git a/src/library/scala/collection/immutable/HashSet.scala b/src/library/scala/collection/immutable/HashSet.scala
index e79b456a2f..4779702ea7 100644
--- a/src/library/scala/collection/immutable/HashSet.scala
+++ b/src/library/scala/collection/immutable/HashSet.scala
@@ -15,16 +15,19 @@ package immutable
 import generic._
 import annotation.unchecked.uncheckedVariance
 
-/**
- *  This class implements immutable sets using a hash trie.
+/** This class implements immutable sets using a hash trie.
  *
- * @note the builder of a hash set returns specialized representations `EmptySet`,`Set1`,..., `Set4`
- * for sets of `size <= 4`.
+ *  <b>Note:</b> 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.
  *
  *  @author  Martin Odersky
  *  @author  Tiark Rompf
  *  @version 2.8
  *  @since   2.3
+ *  @define Coll immutable.HashSet
+ *  @define coll immutable hash set
  */
 @serializable @SerialVersionUID(2L)
 class HashSet[A] extends Set[A]
@@ -83,14 +86,19 @@ object HashSet extends SetFactory[HashSet] {
 */
 
 
-/** A factory object for immutable HashSets.
+/** $factoryInfo
+ *  @define Coll immutable.HashSet
+ *  @define coll immutable hash set
  *
- *  @author  Martin Odersky
  *  @author  Tiark Rompf
- *  @version 2.8
  *  @since   2.3
+ *  @define Coll immutable.HashSet
+ *  @define coll immutable hash set
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 object HashSet extends SetFactory[HashSet] {
+  /** $setCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, HashSet[A]] = setCanBuildFrom[A]
   override def empty[A]: HashSet[A] = EmptyHashSet.asInstanceOf[HashSet[A]]
 
diff --git a/src/library/scala/collection/immutable/IndexedSeq.scala b/src/library/scala/collection/immutable/IndexedSeq.scala
index 268bd56a85..4064e9e3a9 100644
--- a/src/library/scala/collection/immutable/IndexedSeq.scala
+++ b/src/library/scala/collection/immutable/IndexedSeq.scala
@@ -14,7 +14,7 @@ package immutable
 import generic._
 import mutable.{ArrayBuffer, Builder}
 
-/** A subtrait of <code>collection.IndexedSeq</code> which represents indexed sequences
+/** A subtrait of `collection.IndexedSeq` which represents indexed sequences
  *  that are guaranteed immutable.
  *  $indexedSeqInfo
  */
diff --git a/src/library/scala/collection/immutable/IntMap.scala b/src/library/scala/collection/immutable/IntMap.scala
index 75a25e0223..90dfa541e3 100644
--- a/src/library/scala/collection/immutable/IntMap.scala
+++ b/src/library/scala/collection/immutable/IntMap.scala
@@ -12,8 +12,8 @@
 package scala.collection
 package immutable;
 
-/**
- * @author David MacIver
+/** Utility class for integer maps.
+ *  @author David MacIver
  */
 private[immutable] object IntMapUtils {
   def zero(i : Int, mask : Int) = (i & mask) == 0;
@@ -50,8 +50,8 @@ private[immutable] object IntMapUtils {
 
 import IntMapUtils._
 
-/**
- * @since 2.7
+/** A companion object for integer maps.
+ *  @since 2.7
  */
 object IntMap {
   def empty[T] : IntMap[T]  = IntMap.Nil;
@@ -146,15 +146,19 @@ private[immutable] class IntMapKeyIterator[V](it : IntMap[V]) extends IntMapIter
 
 import IntMap._
 
-/**
- * Specialised immutable map structure for integer keys, based on
- * <a href="http://citeseer.ist.psu.edu/okasaki98fast.html">Fast Mergeable Integer Maps</a>
- * by Okasaki and Gill. Essentially a trie based on binary digits of the the integers.
+/** Specialised immutable map structure for integer keys, based on
+ *  <a href="http://citeseer.ist.psu.edu/okasaki98fast.html">Fast Mergeable Integer Maps</a>
+ *  by Okasaki and Gill. Essentially a trie based on binary digits of the the integers.
  *
- * Note: This class is as of 2.8 largely superseded by HashMap.
+ *  Note: This class is as of 2.8 largely superseded by HashMap.
  *
- * @since 2.7
+ *  @tparam T    type of the values associated with integer keys.
  *
+ *  @since 2.7
+ *  @define Coll immutable.IntMap
+ *  @define coll immutable integer map
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap[T]] {
   override def empty: IntMap[T] = IntMap.Nil;
diff --git a/src/library/scala/collection/immutable/Iterable.scala b/src/library/scala/collection/immutable/Iterable.scala
index 795fc2fa92..e0ef5ffcc1 100644
--- a/src/library/scala/collection/immutable/Iterable.scala
+++ b/src/library/scala/collection/immutable/Iterable.scala
@@ -17,6 +17,9 @@ import mutable.Builder
 
 /** A base trait for iterable collections that are guaranteed immutable.
  *  $iterableInfo
+ *
+ *  @define Coll immutable.Iterable
+ *  @define coll immutable iterable collection
  */
 trait Iterable[+A] extends Traversable[A]
                       with scala.collection.Iterable[A]
@@ -25,14 +28,11 @@ trait Iterable[+A] extends Traversable[A]
   override def companion: GenericCompanion[Iterable] = Iterable
 }
 
-/** A factory object for the trait <code>Iterable</code>.
- *
- *  @author   Martin Odersky
- *  @version 2.8
- *  @since   2.8
+/** $factoryInfo
+ *  @define Coll immutable.Iterable
+ *  @define coll immutable iterable collection
  */
 object Iterable extends TraversableFactory[Iterable] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Iterable[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, Iterable[A]] = new mutable.ListBuffer
 }
-
diff --git a/src/library/scala/collection/immutable/LinearSeq.scala b/src/library/scala/collection/immutable/LinearSeq.scala
index 9cb35dced5..1ffe96310e 100644
--- a/src/library/scala/collection/immutable/LinearSeq.scala
+++ b/src/library/scala/collection/immutable/LinearSeq.scala
@@ -15,7 +15,7 @@ package immutable
 import generic._
 import mutable.Builder
 
-/** A subtrait of <code>collection.LinearSeq</code> which represents sequences that
+/** A subtrait of `collection.LinearSeq` which represents sequences that
  *  are guaranteed immutable.
  *  $linearSeqInfo
  */
diff --git a/src/library/scala/collection/immutable/ListMap.scala b/src/library/scala/collection/immutable/ListMap.scala
index 4342e54a9d..13d5bbe2ac 100644
--- a/src/library/scala/collection/immutable/ListMap.scala
+++ b/src/library/scala/collection/immutable/ListMap.scala
@@ -14,9 +14,10 @@ package immutable
 
 import generic._
 
-/** The canonical factory of <a href="ListMap.html">ListMap</a>'s.
- *
+/** $factoryInfo
  *  @since 1
+ *  @define Coll immutable.ListMap
+ *  @define coll immutable list map
  */
 object ListMap extends ImmutableMapFactory[ListMap] {
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), ListMap[A, B]] =
@@ -25,14 +26,21 @@ object ListMap extends ImmutableMapFactory[ListMap] {
 }
 
 /** This class implements immutable maps using a list-based data
- *  structure. Instances of <code>ListMap</code> represent
+ *  structure. Instances of `ListMap` represent
  *  empty maps; they can be either created by calling the constructor
- *  directly, or by applying the function <code>ListMap.empty</code>.
+ *  directly, or by applying the function `ListMap.empty`.
+ *
+ *  @tparam A     the type of the keys in this list map.
+ *  @tparam B     the type of the values associated with the keys.
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
  *  @version 2.0, 01/01/2007
  *  @since   1
+ *  @define Coll immutable.ListMap
+ *  @define coll immutable list map
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(301002838095710379L)
 class ListMap[A, +B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] {
@@ -45,7 +53,7 @@ class ListMap[A, +B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] {
    */
   override def size: Int = 0
 
-  /** Checks if this map maps <code>key</code> to a value and return the
+  /** Checks if this map maps `key` to a value and return the
    *  value if it exists.
    *
    *  @param  key the key of the mapping of interest
diff --git a/src/library/scala/collection/immutable/ListSet.scala b/src/library/scala/collection/immutable/ListSet.scala
index f7b76d2317..2a202df9ef 100644
--- a/src/library/scala/collection/immutable/ListSet.scala
+++ b/src/library/scala/collection/immutable/ListSet.scala
@@ -14,24 +14,32 @@ package immutable
 
 import generic._
 
-/** The canonical factory of <a href="ListSet.html">ListSet</a>'s
- *
+/** $factoryInfo
+ *  @define Coll immutable.ListSet
+ *  @define coll immutable list set
  *  @since 1
  */
 object ListSet extends SetFactory[ListSet] {
+  /** setCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ListSet[A]] = setCanBuildFrom[A]
   override def empty[A] = new ListSet[A]
 }
 
 
 /** This class implements immutable sets using a list-based data
- *  structure. Instances of <code>ListSet</code> represent
+ *  structure. Instances of `ListSet` represent
  *  empty sets; they can be either created by calling the constructor
- *  directly, or by applying the function <code>ListSet.empty</code>.
+ *  directly, or by applying the function `ListSet.empty`.
+ *
+ *  @tparam A    the type of the elements contained in this list set.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 09/07/2003
  *  @since   1
+ *  @define Coll immutable.ListSet
+ *  @define coll immutable list set
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable
 class ListSet[A] extends Set[A]
diff --git a/src/library/scala/collection/immutable/LongMap.scala b/src/library/scala/collection/immutable/LongMap.scala
index 24afb65b99..f31089d24c 100644
--- a/src/library/scala/collection/immutable/LongMap.scala
+++ b/src/library/scala/collection/immutable/LongMap.scala
@@ -1,8 +1,8 @@
 package scala.collection
 package immutable
 
-/**
- * @author David MacIver
+/** Utility class for long maps.
+ *  @author David MacIver
  */
 private[immutable] object LongMapUtils{
   def zero(i : Long, mask : Long) = (i & mask) == 0L;
@@ -40,8 +40,8 @@ private[immutable] object LongMapUtils{
 
 import LongMapUtils._
 
-/**
- * @since 2.7
+/** A companion object for long maps.
+ *  @since 2.7
  */
 object LongMap{
   def empty[T] : LongMap[T]  = LongMap.Nil;
@@ -134,13 +134,19 @@ private[immutable] class LongMapKeyIterator[V](it : LongMap[V]) extends LongMapI
 import LongMap._;
 
 /**
- * Specialised immutable map structure for long keys, based on
- * <a href="http://citeseer.ist.psu.edu/okasaki98fast.html">Fast Mergeable Long Maps</a>
- * by Okasaki and Gill. Essentially a trie based on binary digits of the the integers.
+ *  Specialised immutable map structure for long keys, based on
+ *  <a href="http://citeseer.ist.psu.edu/okasaki98fast.html">Fast Mergeable Long Maps</a>
+ *  by Okasaki and Gill. Essentially a trie based on binary digits of the the integers.
+ *
+ *  Note: This class is as of 2.8 largely superseded by HashMap.
  *
- * Note: This class is as of 2.8 largely superseded by HashMap.
+ *  @tparam T      type of the values associated with the long keys.
  *
- * @since 2.7
+ *  @since 2.7
+ *  @define Coll immutable.LongMap
+ *  @define coll immutable long integer map
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, LongMap[T]] {
   override def empty: LongMap[T] = LongMap.Nil;
@@ -185,7 +191,7 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
     case LongMap.Bin(_, _, left, right) => {left.foreachKey(f); right.foreachKey(f); }
     case LongMap.Tip(key, _) => f(key);
     case LongMap.Nil => {}
-  }
+
 
   override def valuesIterator : Iterator[T] = this match {
     case LongMap.Nil => Iterator.empty;
diff --git a/src/library/scala/collection/mutable/IndexedSeq.scala b/src/library/scala/collection/mutable/IndexedSeq.scala
index 14ee5afc9b..a0b90f63df 100644
--- a/src/library/scala/collection/mutable/IndexedSeq.scala
+++ b/src/library/scala/collection/mutable/IndexedSeq.scala
@@ -16,7 +16,6 @@ import generic._
 
 /** A subtrait of `collection.IndexedSeq` which represents sequences
  *  that can be mutated.
- *
  *  $indexedSeqInfo
  */
 trait IndexedSeq[A] extends Seq[A]
diff --git a/src/library/scala/collection/mutable/ListMap.scala b/src/library/scala/collection/mutable/ListMap.scala
index a4321d3818..09b0c6459b 100644
--- a/src/library/scala/collection/mutable/ListMap.scala
+++ b/src/library/scala/collection/mutable/ListMap.scala
@@ -59,8 +59,8 @@ class ListMap[A, B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] {
 }
 
 /** $factoryInfo
- *  @define Coll ListMap
- *  @define coll list map
+ *  @define Coll mutable.ListMap
+ *  @define coll mutable list map
  */
 object ListMap extends MutableMapFactory[ListMap] {
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), ListMap[A, B]] = new MapCanBuildFrom[A, B]