Improve range-operation documentation for lists.

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 33e011c09060163842f50a29bc71da1824ebeb98..9f13798074bc8c1086a3415bd88410012be413b7 100644
--- a/sdk/lib/core/list.dart
+++ b/sdk/lib/core/list.dart
@@ -415,12 +415,15 @@ abstract class List<E> implements EfficientLengthIterable<E> {
    * Returns an [Iterable] that iterates over the objects in the range
    * [start] inclusive to [end] exclusive.
    *
-   * An error occurs if [end] is before [start].
+   * The provide range, given by [start] and [end], must be valid at the time
+   * of the call.
    *
-   * An error occurs if the [start] and [end] are not valid ranges at the time
-   * of the call to this method. The returned [Iterable] behaves like
-   * `skip(start).take(end - start)`. That is, it does not throw exceptions
-   * if `this` changes size.
+   * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
+   * `len` is this list's `length`. The range starts at `start` and has length
+   * `end - start`. An empty range (with `end == start`) is valid.
+   *
+   * The returned [Iterable] behaves like `skip(start).take(end - start)`.
+   * That is, it does *not* throw exceptions if this list changes size.

[Lasse Reichstein Nielsen, 2017/01/17 15:56:59]

Drop "exceptions" (it's errors if it's anything).

[floitsch, 2017/01/18 12:54:18]

Done.

    *
    *     List<String> colors = ['red', 'green', 'blue', 'orange', 'pink'];
    *     Iterable<String> range = colors.getRange(1, 4);
@@ -441,15 +444,17 @@ abstract class List<E> implements EfficientLengthIterable<E> {
    *     list1.setRange(1, 3, list2, 3);
    *     list1.join(', '); // '1, 8, 9, 4'
    *
-   * The [start] and [end] indices must satisfy `0 ≤ start ≤ end ≤ length`.
-   * If [start] equals [end], this method has no effect.
+   * The provide range, given by [start] and [end], must be valid.
+   * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
+   * `len` is this list's `length`. The range starts at `start` and has length
+   * `end - start`. An empty range (with `end == start`) is valid.
    *
    * The [iterable] must have enough objects to fill the range from `start`
    * to `end` after skipping [skipCount] objects.
    *
-   * If `iterable` is this list, the operation will copy the elements originally
-   * in the range from `skipCount` to `skipCount + (end - start)` to the
-   * range `start` to `end`, even if the two ranges overlap.
+   * If `iterable` is this list, the operation will copies the elements

[Lasse Reichstein Nielsen, 2017/01/17 15:56:58]

drop "will"

[floitsch, 2017/01/18 12:54:18]

Done.

+   * originally in the range from `skipCount` to `skipCount + (end - start)` to
+   * the range `start` to `end`, even if the two ranges overlap.
    *
    * If `iterable` depends on this list in some other way, no guarantees are
    * made.
@@ -459,8 +464,10 @@ abstract class List<E> implements EfficientLengthIterable<E> {
   /**
    * Removes the objects in the range [start] inclusive to [end] exclusive.
    *
-   * The [start] and [end] indices must be in the range
-   * `0 ≤ index ≤ length`, and `start ≤ end`.
+   * The provide range, given by [start] and [end], must be valid.
+   * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
+   * `len` is this list's `length`. The range starts at `start` and has length
+   * `end - start`. An empty range (with `end == start`) is valid.
    *
    * Throws an [UnsupportedError] if this is a fixed-length list. In that case
    * the list is not modified.
@@ -471,7 +478,10 @@ abstract class List<E> implements EfficientLengthIterable<E> {
    * Sets the objects in the range [start] inclusive to [end] exclusive
    * to the given [fillValue].
    *
-   * An error occurs if [start]..[end] is not a valid range for `this`.
+   * The provide range, given by [start] and [end], must be valid.
+   * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
+   * `len` is this list's `length`. The range starts at `start` and has length
+   * `end - start`. An empty range (with `end == start`) is valid.
    */
   void fillRange(int start, int end, [E fillValue]);
 
@@ -483,7 +493,10 @@ abstract class List<E> implements EfficientLengthIterable<E> {
    *     list.replaceRange(1, 4, [6, 7]);
    *     list.join(', '); // '1, 6, 7, 5'
    *
-   * An error occurs if [start]..[end] is not a valid range for `this`.
+   * The provide range, given by [start] and [end], must be valid.
+   * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
+   * `len` is this list's `length`. The range starts at `start` and has length
+   * `end - start`. An empty range (with `end == start`) is valid.
    *
    * This method does not work on fixed-length lists, even when [replacement]
    * has the same number of elements as the replaced range. In that case use