Better documentation on Sets and Maps, and more.

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 356 matching lines @@
    *     var list = [1, 2, 3, 4, 5];
    *     list.replaceRange(1, 3, [6, 7, 8, 9]);
    *     print(list);  // [1, 6, 7, 8, 9, 4, 5]
    */
   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.
+   * as values. The [Map.keys] [Iterable] will iterate the indices of this list
+   * in numerical order.
    */
   Map<int, E> asMap();
 }