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

sdk/lib/core/list.dart

 // Copyright (c) 2012, 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 indexable collection of objects with a length.
  *
  * Subclasses of this class implement different kinds of lists.
@@ skipping 70 matching lines @@
    * value at each position with [fill]:
    *
    *     new List<int>.filled(3, 0); // [0, 0, 0]
    *
    * The [length] must be a non-negative integer.
    *
    * If the list is growable, changing its length will not initialize new
    * 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});
 
   /**
    * Creates a list containing all [elements].
    *
    * The [Iterator] of [elements] provides the order of the elements.
    *
    * This constructor returns a growable list when [growable] is true;
    * otherwise, it returns a fixed-length list.
@@ skipping 379 matching lines @@
    * as values. The `Map.keys` [Iterable] iterates the indices of this list
    * in numerical order.
    *
    *     List<String> words = ['fee', 'fi', 'fo', 'fum'];
    *     Map<int, String> map = words.asMap();
    *     map[0] + map[1];   // 'feefi';
    *     map.keys.toList(); // [0, 1, 2, 3]
    */
   Map<int, E> asMap();
 }