Add documentation to List.filled to warn of common mistake.

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 9d25927ef1e60372af1e5c5c1450968fa15347a7..d887e67600a65f636475b4d758f136eb93977ece 100644
--- a/sdk/lib/core/list.dart
+++ b/sdk/lib/core/list.dart
@@ -88,6 +88,24 @@ abstract class List<E> implements Iterable<E>, EfficientLength {
    * entries with [fill]. After being created and filled, the list is
    * no different from any other growable or fixed-length list
    * created using [List].
+   *
+   * All entries in the returned list point to the same provided [fill] value.
+   * That all items in the list are the same object is
+   * observable when the given value is a mutable object.
+   *
+   * ```
+   * var shared = new List.filled(3, []);
+   * shared[0].add(499);
+   * print(shared);  // => [[499], [499], [499]]
+   * ```
+   *
+   * You may use [List.generate] to create a new object for each position in
+   * in the list.
+   * ```
+   * var unique = new List.generate(3, (_) => []);
+   * unique[0].add(499);
+   * print(unique); // => [[499], [], []]
+   * ```
    */
   external factory List.filled(int length, E fill, {bool growable: false});