Fix incorrect range check comments in List.*Range methods' documentation.

corelib/src/list.dart

 // Copyright (c) 2011, 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.
 
 /**
  * A [List] is an indexable collection with a length. It can be of
  * fixed size or extendable.
  */
 interface List<E> extends Collection<E> default ListFactory<E> {
 
@@ skipping 35 matching lines @@
   void add(E value);
 
   /**
    * Adds [value] at the end of the list, extending the length by
    * one. Throws an [UnsupportedOperationException] if the list is not
    * extendable.
    */
   void addLast(E value);
 
   /**
-   * Appends all elements of the [collection] to the end of list.
+   * Appends all elements of the [collection] to the end of the list.
    * Extends the length of the list by the length of [collection].
    * Throws an [UnsupportedOperationException] if the list is not
    * extendable.
    */
   void addAll(Collection<E> collection);
 
   /**
    * Sorts the list according to the order specified by the comparator.
    * The order specified by the comparator must be reflexive,
    * anti-symmetric, and transitive.
    *
    * The comparator function [compare] must take two arguments [a] and [b]
    * and return
    *
    *   an integer strictly less than 0 if a < b,
    *   0 if a = b, and
    *   an integer strictly greater than 0 if a > b.
    */
   void sort(int compare(E a, E b));
 
   /**
-   * Returns the first index of [element] in this list. Searches this
+   * Returns the first index of [element] in the list. Searches the
    * list from index [start] to the length of the list. Returns
    * -1 if [element] is not found.
    */
   int indexOf(E element, [int start]);
 
   /**
-   * Returns the last index of [element] in this list. Searches this
+   * Returns the last index of [element] in the list. Searches the
    * list from index [start] (inclusive) to 0. Returns -1 if
    * [element] is not found.
    */
   int lastIndexOf(E element, [int start]);
 
   /**
    * Removes all elements in the list. The length of the list
    * becomes zero. Throws an [UnsupportedOperationException] if
    * the list is not extendable.
    */
   void clear();
 
   /**
    * Pops and returns the last element of the list.
    * Throws a [UnsupportedOperationException] if the length of the
    * list cannot be changed.
    */
   E removeLast();
 
   /**
    * Returns the last element of the list, or throws an out of bounds
    * exception if the list is empty.
    */
   E last();
 
   /**
-   * Returns a sub list copy of this list, from [start] to
-   * [:start + length:].
+   * Returns a sub list copy of the list, from [start] to

[Bob Nystrom, 2012/05/16 16:22:37]

"sub" isn't a word (or, at least, not in this context). How about:

"Returns a new list containing [length] elements from this list starting at
[start]."

[Bill Hesse, 2012/05/21 10:26:01]

Done.

+   * [:start + length - 1:] inclusive.
    * Returns an empty list if [length] is 0.
    * Throws an [IllegalArgumentException] if [length] is negative.
    * Throws an [IndexOutOfRangeException] if [start] or
-   * [:start + length:] are out of range.
+   * [:start + length - 1:] are out of range.
    */
   List<E> getRange(int start, int length);
 
   /**
-   * Copies [length] elements of the [from] array, starting
+   * Copies [length] elements of the [from] list, starting
    * from [startFrom], into [:this:], starting at [start].

[Bob Nystrom, 2012/05/16 16:22:37]

[:this:] -> this list

[Bill Hesse, 2012/05/21 10:26:01]

Done.

    * If [length] is 0, this method does not do anything.
    * Throws an [IllegalArgumentException] if [length] is negative.
    * Throws an [IndexOutOfRangeException] if [start] or
-   * [:start + length:] are out of range for [:this:], or if
-   * [startFrom] is out of range for [from].
+   * [:start + length - 1:] are out of range for [:this:], or if
+   * [startFrom] or [:startFrom + length - 1:] are out of range for [from].
    */
   void setRange(int start, int length, List<E> from, [int startFrom]);
 
   /**
-   * Removes the range in the list starting from [start] to
-   * [:start + length:].
+   * Removes from the list the range from [start] to

[Bob Nystrom, 2012/05/16 16:22:37]

"Removes [length] elements from this list, beginning at [start]."

[Bill Hesse, 2012/05/21 10:26:01]

Done.

+   * [:start + length - 1:], inclusive.
    * Throws an [UnsupportedOperationException] if the list is
    * not extendable.
    * If [length] is 0, this method does not do anything.
    * Throws an [IllegalArgumentException] if [length] is negative.
    * Throws an [IndexOutOfRangeException] if [start] or
-   * [:start + length:] are out of range.
+   * [:start + length: - 1] are out of range.
    */
   void removeRange(int start, int length);
 
   /**
-   * Inserts a new range in the list, starting from [start] to
-   * [:start + length:]. The entries are filled with [initialValue].
+   * Inserts a new range into the list, starting from [start] to
+   * [:start + length - 1:]. The entries are filled with [initialValue].
    * Throws an [UnsupportedOperationException] if the list is
    * not extendable.
    * If [length] is 0, this method does not do anything.
-   * If [start] is the length of the array, this method inserts the
-   * range at the end of the array.
+   * If [start] is the length of the list, this method inserts the
+   * range at the end of the list.
    * Throws an [IllegalArgumentException] if [length] is negative.
-   * Throws an [IndexOutOfRangeException] if [start] or
-   * [:start + length:] are out of range.
+   * Throws an [IndexOutOfRangeException] if [start] is negative or if
+   * [start] is greater than the length of the list.
    */
   void insertRange(int start, int length, [E initialValue]);
 }