Update List.sort documentation to state that it isn't stable.

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 174 matching lines @@
   /**
    * Returns an [Iterable] of the objects in this list in reverse order.
    */
   Iterable<E> get reversed;
 
   /**
    * Sorts this list according to the order specified by the [compare] function.
    *
    * The [compare] function must act as a [Comparator].
    *
-   *     List<String> numbers = ['one', 'two', 'three', 'four'];
+   *     List<String> numbers = ['two', 'three', 'four'];
    *     // Sort from shortest to longest.
-   *     numbers.sort((x, y) => x.length.compareTo(y.length));
-   *     numbers.join(', '); // 'one, two, four, three'
+   *     numbers.sort((a, b) => a.length.compareTo(b.length));
+   *     print(numbers);  // [two, four, three]
    *
    * The default List implementations use [Comparable.compare] if
    * [compare] is omitted.
    *
    *     List<int> nums = [13, 2, -11];
    *     nums.sort();
-   *     nums.join(', '); // '-11, 2, 13'
+   *     print(nums);  // [-11, 2, 13]
+   *
+   * A [Comparator] may compare objects as equal (return zero), even if they
+   * are distinct objects.
+   * The sort function is not guaranteed to be stable, so distinct objects
+   * that compare as equal may occur in any order in the result:
+   *
+   *     List<String> numbers = ['one', 'two', 'three', 'four'];
+   *     numbers.sort((a, b) => a.length.compareTo(b.length));
+   *     print(numbers);  // [one, two, four, three] OR [two, one, four, three]

[eernst, 2015/12/08 09:02:08]

It is slightly confusing that `print(numbers)` omits the quotes (sure, it does
leave out the quotes, but I couldn't help wondering whether it's accurate), so
maybe the `join` example (where the reader is nudged toward thinking about
string processing) wasn't so bad. On the other hand it was confusing that the
`join` statement produced and then ignored the string mentioned in the comment.
So, OK, `print` is better.

I trust you on the main thing, which is that `List.sort` is actually allowed to
be non-stable.

    */
   void sort([int compare(E a, E b)]);
 
   /**
    * Shuffles the elements of this list randomly.
    */
   void shuffle([Random random]);
 
   /**
    * Returns the first index of [element] in this list.
@@ skipping 255 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();
 }