mutable.MapLike: override $mapNote to reflect actual require mutable api

The api needed to define a mutable.Map is different then the one
needed to define an immutable.Map. Prior to this patch the mutable one
reflected the api needed for the immutable one causing confusion about
what really needed to be defined.

1 files changed, 22 insertions, 0 deletions

diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala
index b8b1152099..3046207533 100644
--- a/src/library/scala/collection/mutable/MapLike.scala
+++ b/src/library/scala/collection/mutable/MapLike.scala
@@ -18,6 +18,28 @@ import parallel.mutable.ParMap
  *  $mapNote
  *  $mapTags
  *  @since   2.8
+ *
+ * @define mapNote
+ *    '''Implementation note:'''
+ *    This trait provides most of the operations of a mutable `Map`
+ *    independently of its representation. It is typically inherited by
+ *    concrete implementations of maps.
+ *
+ *    To implement a concrete mutable map, you need to provide
+ *    implementations of the following methods:
+ *    {{{
+ *       def get(key: A): Option[B]
+ *       def iterator: Iterator[(A, B)]
+ *       def += (kv: (A, B)): This
+ *       def -= (key: A): This
+ *    }}}
+ *    If you wish that methods like `take`, `drop`, `filter` also return the same kind of map
+ *    you should also override:
+ *    {{{
+ *       def empty: This
+ *    }}}
+ *    It is also good idea to override methods `foreach` and
+ *    `size` for efficiency.
  */
 trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
   extends scala.collection.MapLike[A, B, This]