Improve List documentation.

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 0b62f2ad23c3cac275a409e76193d3a27517c154..59a15631dfeb5fae5c2d9a85df9dafd426b0d3a4 100644
--- a/sdk/lib/core/list.dart
+++ b/sdk/lib/core/list.dart
@@ -52,6 +52,8 @@ abstract class List<E> implements Iterable<E> {
    *
    * The list is a fixed-length list if [length] is provided, and an empty
    * growable list if [length] is omitted.
+   *
+   * It is an error if [length] is not a non-negative integer.

[Søren Gjesse, 2013/04/24 12:02:20]

State the obvious :-)

[Lasse Reichstein Nielsen, 2013/04/24 12:09:51]

Can't be too careful :)
Another option would be to use zero for all negative numbers.

    */
   external factory List([int length]);
 
@@ -62,8 +64,10 @@ abstract class List<E> implements Iterable<E> {
   external factory List.filled(int length, E fill);
 
   /**
-   * Creates an list with the elements of [other]. The order in
-   * the list will be the order provided by the iterator of [other].
+   * Creates an list with the elements of [other].
+   *
+   * The order in the list will be
+   * the order provided by the iterator of [other].
    *
    * The returned list is growable if [growable] is true, otherwise it's
    * a fixed length list.
@@ -83,11 +87,12 @@ abstract class List<E> implements Iterable<E> {
   }
 
   /**
-   * Generate a `List` of elements.
+   * Generate a `List` of values.
    *
-   * Generates a list of values, where the values are created by
-   * calling the [generator] function for each index in the range
-   * 0 .. [length] - 1.
+   * Creates a list with [length] positions
+   * and fills them by values created by calling [generator]
+   * for each index in the range `0` .. `[length] - 1`
+   * in increasing order.
    *
    * The created length's length is fixed unless [growable] is true.
    */