Document that concurrent modification is bad, m'kay.

sdk/lib/core/map.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * An unordered collection of key-value pairs, from which you retrieve a value
  * by using its associated key.
  *
  * Each key can occur at most once in a map.
+ *
+ * It is generally not allowed to modify the map (add or remove keys) while
+ * an operation is being performed on the map, for example in functions called
+ * during a [forEach] or [putIfAbsent] call.
+ * Modifying the map while iterating the keys or values will also most likely
+ * break the iteration.
  */
 abstract class Map<K, V> {
   /**
    * Creates a Map instance with the default implementation.
    */
   factory Map() = LinkedHashMap<K, V>;
 
   /**
    * Creates a Map instance that contains all key-value pairs of [other].
    */
@@ skipping 147 matching lines @@
   /**
    * Returns true if there is no {key, value} pair in the map.
    */
   bool get isEmpty;
 
   /**
    * Returns true if there is at least one {key, value} pair in the map.
    */
   bool get isNotEmpty;
 }