Document that concurrent modification is bad, m'kay.

sdk/lib/core/iterable.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 object that uses an [Iterator] to serve objects one at a time.
  *
  * You can iterate over all objects served by an Iterable object
  * using the for-in loop construct.
  * For example, you can iterate over all of the keys in a [Map],
  * because Map keys are iterable.
  *
  *     Map kidsBooks = {'Matilda': 'Roald Dahl',
  *                      'Green Eggs and Ham': 'Dr Seuss',
  *                      'Where the Wild Things Are': 'Maurice Sendak'};
  *     for (var book in kidsBooks.keys) {
  *       print('$book was written by ${kidsBooks[book]}');
  *     }
  *
  * The [List] class and the [Set] class implement this interface,
  * as do classes in the [dart:collection](#dart-collection) library.
  *
  * You can implement Iterable in your own class.
  * If you do, then an instance of your Iterable class
  * can be the right-hand side of a for-in construct.
+ *
+ * Some subclasss of `Iterable` can be modified. It is generally not allowed
+ * to modify such collections while they are being iterated. Doing so will break
+ * the iteration, which is typically signalled by throwing a
+ * [ConcurrentModificationError] when it is detected.
  */
 abstract class Iterable<E> {
   const Iterable();
 
   /**
    * Creates an Iterable that generates its elements dynamically.
    *
    * The Iterators created by the Iterable count from
    * zero to [:count - 1:] while iterating, and call [generator]
    * with that index to create the next value.
@@ skipping 280 matching lines @@
  */
 abstract class BidirectionalIterator<E> implements Iterator<E> {
   /**
    * Move back to the previous element.
    *
    * Returns true and updates [current] if successful. Returns false
    * and sets [current] to null if there is no previous element.
    */
   bool movePrevious();
 }