comment updates for various set and map classes...

comment updates for various set and map classes and traits

12 files changed, 97 insertions, 72 deletions

diff --git a/src/library/scala/collection/Map.scala b/src/library/scala/collection/Map.scala
index eed6be9290..6b7e7cd0b1 100644
--- a/src/library/scala/collection/Map.scala
+++ b/src/library/scala/collection/Map.scala
@@ -15,20 +15,19 @@ import Predef._
 
 
 /** <p>
- *    This class defines the interface of collections that unambiguously map
- *     keys to values (i.e. a key is mapped to at least one value).
+*     A map is a collection that maps each key to one or zero values.
  *  </p>
  *  <p>
- *    Class <code>Map</code> may only be used for accessing elements from map
- *    implementations. Two different extensions of class <code>Map</code> in
- *    the package <code><a href="mutable$content.html" target="contentFrame">
+ *    This trait provides a limited interface, only allowing reading of elements.
+ *    There are two extensions of this trait, in packages
+ *    <code><a href="mutable$content.html" target="contentFrame">
  *    scala.collection.mutable</a></code>
- *    and  <code><a href="immutable$content.html" target="contentFrame">
- *    scala.collection.immutable</a></code> provide functionality for
- *    adding new key/value mappings to a map. The class in the first package is
- *    implemented by maps that are modified destructively, whereas the class in
- *    the second package is used by functional map implementations that rely on
- *    immutable data structures.
+ *    and <code><a href="immutable$content.html" target="contentFrame">
+ *    scala.collection.immutable</a></code>, which provide functionality for
+ *    adding new key/value mappings to a map. The trait in the first package is
+ *    for maps that are modified destructively, whereas the trait in
+ *    the second package is for immutable maps which create a new map
+ *    when something is added or removed from them.
  *  </p>
  *
  *  @author  Matthias Zenger
diff --git a/src/library/scala/collection/Set.scala b/src/library/scala/collection/Set.scala
index 2de995df25..94cb1d9256 100644
--- a/src/library/scala/collection/Set.scala
+++ b/src/library/scala/collection/Set.scala
@@ -13,22 +13,19 @@ package scala.collection
 
 
 /** <p>
- *    This class defines the interface of collections that do not contain
- *    duplicate elements.
+ *    A set is a collection that includes at most one of any object.
  *  </p>
  *  <p>
- *    Class <code>Set</code> may only be used for accessing elements
- *    from set implementations. Two different extensions
- *    of class <code>Set</code> in the package
+ *    This trait provides a limited interface, only allowing reading of elements.
+ *    There are two extensions of this trait, in packages
  *    <code><a href="mutable$content.html" target="contentFrame">
- *    scala.collection.mutable</a></code> and
- *    <code><a href="immutable$content.html" target="contentFrame">
- *    scala.collection.immutable</a></code> provide functionality for adding
- *    new elements to a set. The class in the first package is implemented
- *    by sets the are modified destructively, whereas the class in the second
- *    package is used by functional set implementations that rely on immutable
- *    data structures.
- *  </p>
+ *    scala.collection.mutable</a></code>
+ *    and <code><a href="immutable$content.html" target="contentFrame">
+ *    scala.collection.immutable</a></code>, which provide functionality for
+ *    adding and removing objects from the set. The trait in the first package is
+ *    for sets that are modified destructively, whereas the trait in
+ *    the second package is for immutable sets which create a new set
+ *    when something is added or removed to them.
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
diff --git a/src/library/scala/collection/immutable/HashMap.scala b/src/library/scala/collection/immutable/HashMap.scala
index a87b473f7a..93f64d0fdb 100644
--- a/src/library/scala/collection/immutable/HashMap.scala
+++ b/src/library/scala/collection/immutable/HashMap.scala
@@ -13,7 +13,7 @@ package scala.collection.immutable
 
 import Predef._
 
-/** This class implements immutable maps using a hashtable.
+/** The canonical factory methods for <a href="HashMap.html">immutable HashMap's</a>.
  *
  *  @author  Martin Odersky
  *  @version 2.0, 19/01/2007
@@ -28,6 +28,11 @@ object HashMap {
   def apply[A, B](elems: (A, B)*) = empty[A, B] ++ elems
 }
 
+/** This class implements immutable maps using a hash table.
+  *
+  *  @author  Martin Odersky
+  *  @version 2.0, 19/01/2007
+  */
 @serializable
 class HashMap[A, B] extends Map[A,B] with mutable.HashTable[A] {
   type Entry = mutable.DefaultEntry[A, Any]
diff --git a/src/library/scala/collection/immutable/HashSet.scala b/src/library/scala/collection/immutable/HashSet.scala
index 05f5fd11d1..0b47460408 100644
--- a/src/library/scala/collection/immutable/HashSet.scala
+++ b/src/library/scala/collection/immutable/HashSet.scala
@@ -10,6 +10,11 @@
 
 package scala.collection.immutable
 
+/** The canonical factory methods for <a href="HashSet.html">immutable HashSet's<la>.
+  *
+  *  @author  Martin Odersky
+  *  @version 2.0, 19/01/2007
+  */
 object HashSet {
 
   /** The empty set of this type.
@@ -21,6 +26,11 @@ object HashSet {
   def apply[A, B](elems: A*) = empty[A] ++ elems
 }
 
+/** This class implements immutable sets using a hash table.
+  *
+  *  @author  Martin Odersky
+  *  @version 2.0, 19/01/2007
+  */
 @serializable
 class HashSet[A] extends Set[A] with mutable.FlatHashTable[A] {
   protected var later: HashSet[A] = null
diff --git a/src/library/scala/collection/immutable/ListMap.scala b/src/library/scala/collection/immutable/ListMap.scala
index c0c20a32e7..3813154492 100644
--- a/src/library/scala/collection/immutable/ListMap.scala
+++ b/src/library/scala/collection/immutable/ListMap.scala
@@ -12,6 +12,7 @@
 
 package scala.collection.immutable
 
+/** The canonical factory of <a href="ListMap.html">ListMap</a>'s */
 object ListMap {
 
   /** The empty map of this type
diff --git a/src/library/scala/collection/immutable/ListSet.scala b/src/library/scala/collection/immutable/ListSet.scala
index 8e801fe215..bd0f4d50bd 100644
--- a/src/library/scala/collection/immutable/ListSet.scala
+++ b/src/library/scala/collection/immutable/ListSet.scala
@@ -14,6 +14,7 @@ package scala.collection.immutable
 
 //import Predef.NoSuchElementException
 
+/** The canonical factory of <a href="ListSet.html">ListSet</a>'s */
 object ListSet {
 
   /** constructs an empty ListSet
diff --git a/src/library/scala/collection/immutable/Map.scala b/src/library/scala/collection/immutable/Map.scala
index 4c9bc33d05..b7478a4fb1 100644
--- a/src/library/scala/collection/immutable/Map.scala
+++ b/src/library/scala/collection/immutable/Map.scala
@@ -13,14 +13,19 @@ package scala.collection.immutable
 
 import Predef._
 
+/** <p>An object for creating immutable maps. These are implemented using
+  *         <a href="HashMap.html">immutable hash maps</a>.
+  *  </p>*/
+object Map {
+  def empty[A, B]: Map[A, B] = new EmptyMap[A, B]
+
+  def apply[A, B](elems: (A, B)*) = empty[A, B] ++ elems
+}
+
 /** <p>
- *    This class extends the <code>Map</code> interface of collections
- *    that unambiguously map keys to values (i.e. a key is mapped to at
- *    least one value).
- *  </p>
- *  <p>
- *    This class defines the interface for functional map implementations
- *    relying on immutable data structures.
+ *    This class defines the interface for immutable maps.  Operations
+ *    on an immutable map leave the original map unchanged, and return
+ *    a new map if needed.
  *  </p>
  *  <p>
  *    Concrete map implementations have to provide functionality for
@@ -34,16 +39,6 @@ import Predef._
  *  @author  Martin Odersky
  *  @version 1.2, 31/06/2006
  */
-object Map {
-
-  /** The empty map of this type; this is implemented as a treemap */
-  def empty[A, B]: Map[A, B] = new EmptyMap[A, B]
-
-  /** The canonical factory for this type
-   */
-  def apply[A, B](elems: (A, B)*) = empty[A, B] ++ elems
-}
-
 trait Map[A, +B] extends collection.Map[A, B] {
 
   /** This method returns a new map instance of the same class
diff --git a/src/library/scala/collection/immutable/Set.scala b/src/library/scala/collection/immutable/Set.scala
index 0d78403385..8068615191 100644
--- a/src/library/scala/collection/immutable/Set.scala
+++ b/src/library/scala/collection/immutable/Set.scala
@@ -12,31 +12,39 @@
 package scala.collection.immutable
 
 
+/** Canonical factories for immutable sets.  The canonical immutable sets are
+  *  currently implemented using <a href="HashSet.html">immutable hash sets</a>.
+  */
+object Set {
+  /** The empty set of this type
+   */
+  def empty[A]: Set[A] = new EmptySet[A]
+
+  /** The canonical factory for this type
+   */
+  def apply[A](elems: A*) = empty[A] ++ elems
+}
+
 /** <p>
- *    This class represents immutable sets. Concrete set implementations
+ *    This class defines the interface for immutable sets.  Operations
+ *    on an immutable set leave the original set unchanged, and return
+ *    a new set if needed.
+ *  </p>
+
+ *  <p>Concrete set implementations
  *    just have to provide functionality for the abstract methods in
  *    <code>scala.collection.Set</code> as well as for <code>+</code> and
  *    <code>-</code>.
  *  </p>
  *  <p>
  *    Note that abstract immutable.Set's are not covariant in their type
- *    parameter.  This is because some subclasses cannot support the
+ *    parameter.  This is because some implementations cannot support the
  *    <code>+</code> method for arbitrary types.
  *  </p>
  *
  *  @author  Matthias Zenger, Martin Odersky
  *  @version 1.1, 03/05/2004
  */
-object Set {
-  /** The empty set of this type
-   */
-  def empty[A]: Set[A] = new EmptySet[A]
-
-  /** The canonical factory for this type
-   */
-  def apply[A](elems: A*) = empty[A] ++ elems
-}
-
 trait Set[A] extends AnyRef with collection.Set[A] {
 
   /** @return an empty set of arbitrary element type
diff --git a/src/library/scala/collection/immutable/TreeMap.scala b/src/library/scala/collection/immutable/TreeMap.scala
index 7e98e3a1fd..078da93281 100644
--- a/src/library/scala/collection/immutable/TreeMap.scala
+++ b/src/library/scala/collection/immutable/TreeMap.scala
@@ -13,6 +13,7 @@
 package scala.collection.immutable
 
 
+/** The canonical factory of <a href="TreeMap.html">TreeMap</a>'s. */
 object TreeMap {
 
   /** The empty map of this type
diff --git a/src/library/scala/collection/immutable/TreeSet.scala b/src/library/scala/collection/immutable/TreeSet.scala
index 8dd1142557..794293835c 100644
--- a/src/library/scala/collection/immutable/TreeSet.scala
+++ b/src/library/scala/collection/immutable/TreeSet.scala
@@ -11,6 +11,8 @@
 
 package scala.collection.immutable
 
+/** The canonical factory of <a href="TreeSet.html">TreeSet</a>'s. */
+
 object TreeSet {
 
   /** The empty set of this type
diff --git a/src/library/scala/collection/mutable/Map.scala b/src/library/scala/collection/mutable/Map.scala
index 05ee923133..6242eb5fea 100644
--- a/src/library/scala/collection/mutable/Map.scala
+++ b/src/library/scala/collection/mutable/Map.scala
@@ -15,16 +15,10 @@ import Predef._
 
 //import Predef.UnsupportedOperationException
 
-/** This class represents mutable maps. Concrete map implementations
- *  just have to provide functionality for the abstract methods in
- *  <code>scala.collection.Map</code> as well as for <code>update</code>,
- *  and <code>-=</code>.
- *
- *  @author  Matthias Zenger
- *  @author  Martin Odersky
- *  @version 2.0, 31/12/2006
- */
 
+/** The canonical factory methods for <a href="Map.html">mutable maps</a>.  These currently
+  *  return <a href="HashMap.html">HashMap's</a>.
+  */
 object Map {
 
   /** The empty map of this type; this is implemented as a hashtable */
@@ -35,6 +29,15 @@ object Map {
   def apply[A, B](elems: (A, B)*) = empty[A, B] ++ elems
 }
 
+/** This trait represents mutable maps. Concrete map implementations
+ *  just have to provide functionality for the abstract methods in
+ *  <code>scala.collection.Map</code> as well as for <code>update</code>,
+ *  and <code>-=</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @author  Martin Odersky
+ *  @version 2.0, 31/12/2006
+ */
 @cloneable
 trait Map[A, B] extends AnyRef
       with collection.Map[A, B]
diff --git a/src/library/scala/collection/mutable/Set.scala b/src/library/scala/collection/mutable/Set.scala
index 8357e72a5f..a516fef5f2 100644
--- a/src/library/scala/collection/mutable/Set.scala
+++ b/src/library/scala/collection/mutable/Set.scala
@@ -12,15 +12,9 @@
 package scala.collection.mutable
 
 
-/** This class represents mutable sets. Concrete set implementations
- *  just have to provide functionality for the abstract methods in
- *  <a href="../Set.html" target="contentFrame">
- *  <code>scala.collection.Set</code></a> as well as for <code>+=</code>,
- *  <code>-= and <code>clear</code>.
- *
- *  @author  Matthias Zenger
- *  @version 1.1, 09/05/2004
- */
+/** The canonical factory methods for <a href="Set.html">mutable sets</a>.
+   * Currently these return <a href="HashSet.html">HashSet's</a>.
+   */
 object Set {
 
   /** The empty map of this type; this is implemented as a hashtable */
@@ -31,6 +25,15 @@ object Set {
   def apply[A](elems: A*) = empty[A] ++ elems
 }
 
+/** This class represents mutable sets. Concrete set implementations
+ *  just have to provide functionality for the abstract methods in
+ *  <a href="../Set.html" target="contentFrame">
+ *  <code>scala.collection.Set</code></a> as well as for <code>+=</code>,
+ *  <code>-= and <code>clear</code>.
+ *
+ *  @author  Matthias Zenger
+ *  @version 1.1, 09/05/2004
+ */
 @cloneable
 trait Set[A] extends collection.Set[A] with Scriptable[Message[A]] {