Added more doc-comments.

2 files changed, 73 insertions, 5 deletions

diff --git a/sources/scala/collection/mutable/Map.scala b/sources/scala/collection/mutable/Map.scala
index f6cc9146e2..5d0b7059df 100644
--- a/sources/scala/collection/mutable/Map.scala
+++ b/sources/scala/collection/mutable/Map.scala
@@ -4,10 +4,9 @@
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
+** $Id$
 \*                                                                      */
 
-// $Id$
-
 package scala.collection.mutable;
 
 
@@ -21,35 +20,76 @@ package scala.collection.mutable;
  */
 trait Map[A, B] with scala.collection.Map[A, B] {
 
+    /** This method allows one to add a new mapping from <code>key</code>
+     *  to <code>value</code> to the map. If the map contains already a
+     *  mapping for <code>key</code>, it will be overridden by this
+     *  function.
+     */
     def update(key: A, value: B): Unit;
 
+    /** This method removes a mapping from the given <code>key</code>.
+     *  If the map does not contain a mapping for the given key, the
+     *  method does nothing.
+     */
     def -=(key: A): Unit;
 
+    /** This method defines syntactic sugar for adding or modifying
+     *  mappings. It is typically used in the following way:
+     *  <pre>
+     *  map += key -> value;
+     *  </pre>
+     */
     def +=(key: A): MapTo = new MapTo(key);
 
+    /** <code>incl</code> can be used to add many mappings at the same time
+     *  to the map. The method assumes that a mapping is represented
+     *  by a <code>Pair</code> object who's first component denotes the
+     *  key, and who's second component refers to the value.
+     */
     def incl(mappings: Pair[A, B]*): Unit = {
         val ys = mappings.asInstanceOf[List[Pair[A, B]]];
         ys foreach { case Pair(key, value) => update(key, value); };
     }
 
+    /** This method adds all the mappings provided by an iterator of
+     *  parameter <code>map</code> to the map.
+     */
     def incl(map: Iterable[Pair[A, B]]): Unit = map.elements foreach {
         case Pair(key, value) => update(key, value);
     }
 
+    /** This method will remove all the mappings for the given sequence
+     *  of keys from the map.
+     */
     def excl(keys: A*): Unit = excl(keys);
 
+    /** This method removes all the mappings for keys provided by an
+     *  iterator over the elements of the <code>keys</code> object.
+     */
     def excl(keys: Iterable[A]): Unit = keys.elements foreach -=;
 
+    /** Removes all mappings from the map. After this operation is
+     *  completed, the map is empty.
+     */
     def clear: Unit = keys foreach -=;
 
+    /** This function transforms all the values of mappings contained
+     *  in this map with function <code>f</code>.
+     */
     def map(f: (A, B) => B): Unit = elements foreach {
         case Pair(key, value) => update(key, f(key, value));
     }
 
+    /** This method removes all the mappings for which the predicate
+     *  <code>p</code> returns <code>false</code>.
+     */
     def filter(p: (A, B) => Boolean): Unit = toList foreach {
         case Pair(key, value) => if (p(key, value)) -=(key);
     }
 
+    /** Returns a string representation of this map which shows
+     *  all the mappings.
+     */
     override def toString() =
         if (size == 0)
             "{}"
@@ -63,9 +103,12 @@ trait Map[A, B] with scala.collection.Map[A, B] {
                 res;
             } + "}";
 
+    /** This method controls how a mapping is represented in the string
+     *  representation provided by method <code>toString</code>.
+     */
     def mappingToString(p: Pair[A, B]) = p._1.toString() + " -> " + p._2;
 
-    class MapTo(key: A) {
+    private class MapTo(key: A) {
         def ->(value: B): Unit = update(key, value);
     }
 }
diff --git a/sources/scala/collection/mutable/Set.scala b/sources/scala/collection/mutable/Set.scala
index 665befc255..11691a8bb7 100644
--- a/sources/scala/collection/mutable/Set.scala
+++ b/sources/scala/collection/mutable/Set.scala
@@ -20,28 +20,53 @@ package scala.collection.mutable;
  */
 trait Set[A] with scala.collection.Set[A] {
 
+    /** This method adds a new element to the set.
+     */
     def +=(elem: A): Unit;
 
+    /** <code>incl</code> can be used to add many elements to the set
+     *  at the same time.
+     */
     def incl(elems: A*): Unit = {
         val ys = elems.asInstanceOf[List[A]];
         ys foreach { y => +=(y); };
     }
 
+    /** This method will add all the elements provided by an iterator
+     *  of the iterable object <code>that</code> to the set.
+     */
     def incl(that: Iterable[A]): Unit =
         that.elements.foreach(elem => +=(elem));
 
+    /** <code>-=</code> can be used to remove a single element from
+     *  a set.
+     */
     def -=(elem: A): Unit;
 
+    /** <code>excl</code> removes many elements from the set.
+     */
     def excl(elems: A*): Unit = excl(elems);
 
+    /** This method removes all the elements provided by an iterator
+     *  of the iterable object <code>that</code> from the set.
+     */
     def excl(that: Iterable[A]): Unit =
         that.elements.foreach(elem => -=(elem));
 
+    /** This method computes an intersection with set <code>that</code>.
+     *  It removes all the elements that are not present in <code>that</code>.
+     */
     def intersect(that: Set[A]): Unit = filter(that.contains);
 
-    def clear: Unit;
-
+    /** Method <code>filter</code> removes all elements from the set for
+     *  which the predicate <code>p</code> yields the value <code>false</code>.
+     */
     def filter(p: A => Boolean): Unit = toList foreach {
         elem => if (p(elem)) -=(elem);
     }
+
+    /** Removes all elements from the set. After this operation is completed,
+     *  the set will be empty.
+     */
+    def clear: Unit;
 }