Added comments for #4008.

No review.

1 files changed, 14 insertions, 2 deletions

diff --git a/src/library/scala/collection/mutable/Map.scala b/src/library/scala/collection/mutable/Map.scala
index 5df8594a16..e30a5a4f64 100644
--- a/src/library/scala/collection/mutable/Map.scala
+++ b/src/library/scala/collection/mutable/Map.scala
@@ -26,10 +26,22 @@ trait Map[A, B]
 
   override def empty: Map[A, B] = Map.empty
 
-  /** The same map with a given default function */
+  /** The same map with a given default function.
+   *
+   *  Invoking transformer methods (e.g. `map`) will not preserve the default value.
+   *
+   *  @param d     the function mapping keys to values, used for non-present keys
+   *  @return      a wrapper of the map with a default value
+   */
   def withDefault(d: A => B): mutable.Map[A, B] = new Map.WithDefault[A, B](this, d)
 
-  /** The same map with a given default value */
+  /** The same map with a given default value.
+   *
+   *  Invoking transformer methods (e.g. `map`) will not preserve the default value.
+   *
+   *  @param d     the function mapping keys to values, used for non-present keys
+   *  @return      a wrapper of the map with a default value
+   */
   def withDefaultValue(d: B): mutable.Map[A, B] = new Map.WithDefault[A, B](this, x => d)
 
   /** Return a read-only projection of this map.  !!! or just use an (immutable) MapProxy?