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..48d776cf5f834fd7a620b0dba2e0afb5936e5b48 100644
--- a/sdk/lib/core/list.dart
+++ b/sdk/lib/core/list.dart
@@ -88,6 +88,22 @@ 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 provided [fill] value. This is

[Lasse Reichstein Nielsen, 2016/06/27 18:45:46]

"to the provided"
or even
"to the same provided"


"This is observable" -> "That all items in the list are the same object is
observable ..."

[floitsch, 2016/06/28 00:49:00]

Done.

+   * observable when the given value is a mutable object.
+   *
+   * ```
+   * var shared = new List.filled(3, []);
+   * shared[0].add(499);
+   * print(shared);  // => [[499], [499], [499]]
+   * ```
+   *
+   * If that's not the intended behavior, use [List.generate] instead:

[Lasse Reichstein Nielsen, 2016/06/27 18:45:46]

use [List.generate] instead -> you may use [List.generate] to create a new
object for each position in the created list instead

[floitsch, 2016/06/28 00:49:00]

Done.

+   * ```
+   * var unique = new List.generate(3, (_) => []);
+   * unique[[0].add(499);

[Lasse Reichstein Nielsen, 2016/06/27 18:45:46]

[[ -> [


(I recommend trying examples in dartpad, just to be absolutely sure they run).

[floitsch, 2016/06/28 00:48:59]

I tried in dartpad too, but copied it by hand (because of the "*" in front...).

done.

+   * print(unique); // => [[499], [], []]
+   * ```
    */
   external factory List.filled(int length, E fill, {bool growable: false});