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

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 7f4ab18dfdf63bcf9b125b670926e5703ba3a713..9d25927ef1e60372af1e5c5c1450968fa15347a7 100644
--- a/sdk/lib/core/list.dart
+++ b/sdk/lib/core/list.dart
@@ -192,17 +192,26 @@ abstract class List<E> implements Iterable<E>, EfficientLength {
    *
    * 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)]);