Document that concurrent modification is bad, m'kay.

sdk/lib/core/list.dart

Index: sdk/lib/core/list.dart
diff --git a/sdk/lib/core/list.dart b/sdk/lib/core/list.dart
index 34aefca97b0be729e031833edf93a626bd494664..ce2f310935aae21d1721c6382b33c1dd2a14edaf 100644
--- a/sdk/lib/core/list.dart
+++ b/sdk/lib/core/list.dart
@@ -35,6 +35,13 @@ part of dart.core;
  * lists can throw ConcurrentModificationError. If the length changes
  * temporarily and is restored before continuing the iteration, the iterator
  * does not detect it.
+ *
+ * It is generally not allowed to modify the list's length (adding or removing
+ * elements) while an operation on the list is being performed,
+ * for example during a call to [forEach] or [sort].
+ * Changing the list's length while it is being iterated, either directly or
+ * by iterating an `Iterable` that is backed by the list, will break the

[floitsch, 2013/10/15 15:32:24]

Iterating will not change the length.

[Lasse Reichstein Nielsen, 2013/10/16 05:41:24]

Please elaborate: What do you want changed?

[Lasse Reichstein Nielsen, 2013/10/16 08:53:42]

Ah, now I see how it can also be read. Reworded.

+ * iteration.
  */
 abstract class List<E> implements Iterable<E>, EfficientLength {
   /**
@@ -44,7 +51,7 @@ abstract class List<E> implements Iterable<E>, EfficientLength {
    *
    *     List fixedLengthList = new List(3);
    *     fixedLengthList.length;     // 3
-         fixedLengthList.length = 1; // Error
+   *     fixedLengthList.length = 1; // Error
    *
    *
    * The list has length 0 and is growable if [length] is omitted.