Improve List documentation.

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;
 
 /**
  * A [List] is an indexable collection with a length.
  *
  * A `List` implementation can choose not to support all methods
@@ skipping 34 matching lines @@
  * If the length changes temporarily
  * and is restored before continuing the iteration,
  * the iterator will not detect it.
  */
 abstract class List<E> implements Iterable<E> {
   /**
    * Creates a list of the given [length].
    *
    * 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]);
 
   /**
    * Creates a fixed-length list of the given [length] where each entry
    * contains [fill].
    */
   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.
    */
   factory List.from(Iterable other, { bool growable: true }) {
     List<E> list = new List<E>();
     for (E e in other) {
       list.add(e);
     }
     if (growable) return list;
     int length = list.length;
     List<E> fixedList = new List<E>(length);
     for (int i = 0; i < length; i++) {
       fixedList[i] = list[i];
     }
     return fixedList;
   }
 
   /**
-   * 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.
    */
   factory List.generate(int length, E generator(int index),
                        { bool growable: true }) {
     List<E> result;
     if (growable) {
       result = <E>[]..length = length;
     } else {
       result = new List<E>(length);
@@ skipping 245 matching lines @@
   void replaceRange(int start, int end, Iterable<E> iterable);
 
   /**
    * Returns an unmodifiable [Map] view of `this`.
    *
    * It has the indices of this list as keys, and the corresponding elements
    * as values.
    */
   Map<int, E> asMap();
 }