Scaladoc update for collection.mutable.MultiMap

Addition of source code example on how to use a MultiMap and its
defined methods. Minor correction in documentation for method
`removeBinding`.

1 files changed, 32 insertions, 3 deletions

diff --git a/src/library/scala/collection/mutable/MultiMap.scala b/src/library/scala/collection/mutable/MultiMap.scala
index 31c8a50a84..4635bfbe64 100644
--- a/src/library/scala/collection/mutable/MultiMap.scala
+++ b/src/library/scala/collection/mutable/MultiMap.scala
@@ -15,8 +15,36 @@ package mutable
 /** A trait for mutable maps with multiple values assigned to a key.
  *
  *  This class is typically used as a mixin. It turns maps which map `A`
- *  to `Set[B]` objects into multi maps which map `A` to
- *  `B` objects.
+ *  to `Set[B]` objects into multimaps that map `A` to `B` objects.
+ *
+ *  @example {{{
+ *  // first import all necessary types from package `collection.mutable`
+ *  import collection.mutable.{ HashMap, MultiMap, Set }
+ *
+ *  // to create a `MultiMap` the easiest way is to mixin it into a normal
+ *  // `Map` instance
+ *  val mm = new HashMap[Int, Set[String]] with MultiMap[Int, String]
+ *
+ *  // to add key-value pairs to a multimap it is important to use
+ *  // the method `addBinding` because standard methods like `+` will
+ *  // overwrite the complete key-value pair instead of adding the
+ *  // value to the existing key
+ *  mm.addBinding(1, "a")
+ *  mm.addBinding(2, "b")
+ *  mm.addBinding(1, "c")
+ *
+ *  // mm now contains `Map(2 -> Set(b), 1 -> Set(c, a))`
+ *
+ *  // to check if the multimap contains a value there is method
+ *  // `entryExists`, which allows to traverse the including set
+ *  mm.entryExists(1, _ == "a") == true
+ *  mm.entryExists(1, _ == "b") == false
+ *  mm.entryExists(2, _ == "b") == true
+ *
+ *  // to remove a previous added value there is the method `removeBinding`
+ *  mm.removeBinding(1, "a")
+ *  mm.entryExists(1, _ == "a") == false
+ *  }}}
  *
  *  @define coll multimap
  *  @define Coll `MultiMap`
@@ -57,7 +85,8 @@ trait MultiMap[A, B] extends Map[A, Set[B]] {
     this
   }
 
-  /** Removes the binding of `value` to `key` if it exists.
+  /** Removes the binding of `value` to `key` if it exists, otherwise this
+   *  operation doesn't have any effect.
    *
    *  If this was the last value assigned to the specified key, the
    *  set assigned to that key will be removed as well.