editing doc comments for List class

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.
+ * An indexable collection of objects with a length.
  *
- * A `List` implementation can choose not to support all methods
- * of the `List` interface.
+ * Subclasses of this class implement different kinds of lists.
+ * The most common kinds of lists are:
  *
- * The most common list types are:
- * * Fixed length list. It is an error to use operations that can change
- *   the list's length.
- * * Growable list. Full implementation of the interface.
- * * Unmodifiable list. It is an error to use operations that can change
- *   the list's length, or that can change the values of the list.
+ * * Fixed-length list.
+ *   An error occurs when attempting to use operations
+ *   that can change the length of the list.
+ *
+ * * Growable list. Full implementation of the API defined in this class.
+ *
+ * * Unmodifiable list.

[sethladd, 2013/08/19 15:59:28]

There's also
http://api.dartlang.org/docs/releases/latest/unmodifiable_collection/NonGrowa...

I think it's OK to omit unmodifiable list from this description here. From this
class'es perspective, there's growable and there's fixed length.

[mem, 2013/08/20 21:14:07]

Done.

+ *   An error occurs when attempting to use operations that can change
+ *   the length of the list or the values of the list.
  *   If an unmodifable list is backed by another modifiable data structure,
  *   the values read from it may still change over time.
  *
- * Example:
+ * A List implementation might not support all methods
+ * of the List interface.
+ *
+ * Examples:

[Kathy Walrath, 2013/08/19 22:41:10]

Add some more words here. I wasn't sure what these examples were about. Maybe
combine the two paragraphs. E.g.:

The following code illustrates
that some List implementations
support only a subset of the API:

[mem, 2013/08/20 21:14:07]

Done.

  *
  *     var fixedLengthList = new List(5);
- *     fixedLengthList.length = 0;  // throws.
- *     fixedLengthList.add(499);  // throws
+ *     fixedLengthList.length = 0;  // Error.
+ *     fixedLengthList.add(499);    // Error.
  *     fixedLengthList[0] = 87;
+ *
  *     var growableList = [1, 2];
  *     growableList.length = 0;
  *     growableList.add(499);
  *     growableList[0] = 87;
+ *
  *     var unmodifiableList = const [1, 2];

[Kathy Walrath, 2013/08/19 22:41:10]

delete unmodifiableList example if you remove it from the list o' lists above.

[mem, 2013/08/20 21:14:07]

Done.

- *     unmodifiableList.length = 0;  // throws.
- *     unmodifiableList.add(499);  // throws
- *     unmodifiableList[0] = 87;  // throws.
+ *     unmodifiableList.length = 0; // Error.
+ *     unmodifiableList.add(499);   // Error.
+ *     unmodifiableList[0] = 87;    // Error.
  *
  * Lists are [Iterable].
- * List iteration iterates over values in index order.
- * Changing the values will not affect iteration,
- * but changing the valid indices -
- * that is, changing the list's length -
- * between iteration steps
- * will cause a [ConcurrentModificationError].
+ * Iteration occurs over values in index order.
+ * Changing the values does not affect iteration,
+ * but changing the valid indices—that is,
+ * changing the list's length—between
+ * iteration steps
+ * causes a [ConcurrentModificationError].
  * This means that only growable lists can throw [ConcurrentModificationError].
  * If the length changes temporarily
  * and is restored before continuing the iteration,
- * the iterator will not detect it.
+ * the iterator does not detect it.
  */
 abstract class List<E> implements Iterable<E> {
   /**
    * Creates a list of the given [length].
    *
-   * The list is a fixed-length list if [length] is provided, and an empty
-   * growable list if [length] is omitted.
+   * The list is fixed-length if [length] is provided.
+   * The list has length 0 and is growable if [length] is omitted.
    *
-   * It is an error if [length] is not a non-negative integer.
+   * An error occurs if [length] is negative.
    */
   external factory List([int length]);
 
   /**
-   * Creates a fixed-length list of the given [length] where each entry
-   * contains [fill].
+   * Creates a fixed-length list of the given [length]
+   * and initializes the value at each position with [fill].
    */
   external factory List.filled(int length, E fill);
 
   /**
-   * Creates an list with the elements of [other].
+   * Creates a list and initializes it using the contents of [other].
    *
-   * The order in the list will be
-   * the order provided by the iterator of [other].
+   * The [Iterator] of [other] provides the order of the objects.
    *
-   * The returned list is growable if [growable] is true, otherwise it's
-   * a fixed length list.
+   * This constructor returns a growable list if [growable] is true,

[Kathy Walrath, 2013/08/19 22:41:10]

true, -> true;

[mem, 2013/08/20 21:14:07]

Done.

+   * otherwise, it returns a fixed-length list.
    */
   factory List.from(Iterable other, { bool growable: true }) {
     List<E> list = new List<E>();
     for (E e in other) {
       list.add(e);
     }
     if (growable) return list;
     int length = list.length;
     List<E> fixedList = new List<E>(length);
     for (int i = 0; i < length; i++) {
       fixedList[i] = list[i];
     }
     return fixedList;
   }
 
   /**
-   * Generate a `List` of values.
+   * Generates a list of values.
    *
-   * Creates a list with [length] positions
-   * and fills them by values created by calling [generator]
-   * for each index in the range `0` .. `[length] - 1`
+   * Creates a list with _length_ positions

[Kathy Walrath, 2013/08/19 22:41:10]

shouldn't _length_ be [length]? We should figure out the convention...

[mem, 2013/08/20 21:14:07]

The word length in this context is overloaded. Here it is both the parameter
name and the name of a property in this class. I didn't want it to link to the
property so I used _


On 2013/08/19 22:41:10, Kathy Walrath wrote:

+   * and fills it with values created by calling [generator]
+   * for each index in the range `0` .. `length - 1`
    * in increasing order.
    *
-   * The created list's length is fixed unless [growable] is true.
+   * The length of the created list is fixed unless [growable] is true.

[Kathy Walrath, 2013/08/19 22:41:10]

Use "fixed-length" here?

[mem, 2013/08/20 21:14:07]

Done.

    */
   factory List.generate(int length, E generator(int index),
                        { bool growable: true }) {
     List<E> result;
     if (growable) {
       result = <E>[]..length = length;
     } else {
       result = new List<E>(length);
     }
     for (int i = 0; i < length; i++) {
       result[i] = generator(i);
     }
     return result;
   }
 
   /**
-   * Returns the element at the given [index] in the list or throws
-   * an [RangeError] if [index] is out of bounds.
+   * Returns the object at the given [index] in the list
+   * or throws a [RangeError] if [index] is out of bounds.
    */
   E operator [](int index);
 
   /**
-   * Sets the entry at the given [index] in the list to [value].
-   *
-   * Throws an [RangeError] if [index] is out of bounds.
+   * Sets the value at the given [index] in the list to [value]
+   * or throws a [RangeError] if [index] is out of bounds.
    */
   void operator []=(int index, E value);
 
   /**
-   * Returns the number of elements in the list.
+   * Returns the number of objects in the list.
    *
    * The valid indices for a list are 0 through `length - 1`.
    */
   int get length;
 
   /**
    * Changes the length of the list. If [newLength] is greater than

[Kathy Walrath, 2013/08/19 22:41:10]

add blank line before "If"

[mem, 2013/08/20 21:14:07]

Done.

    * the current [length], entries are initialized to [:null:].
    *
-   * Throws an [UnsupportedError] if the list is not extendable.
+   * Throws an [UnsupportedError] if the list is not growable.
    */
   void set length(int newLength);
 
   /**
-   * Adds [value] at the end of the list, extending the length by
-   * one.
+   * Adds [value] to the end of the list,
+   * extending the length by one.
    *
-   * Throws an [UnsupportedError] if the list is not extendable.
+   * Throws an [UnsupportedError] if the list is not growable.

[Kathy Walrath, 2013/08/19 22:41:10]

the list is not growable -> this is a fixed-length list

[mem, 2013/08/20 21:14:07]

Done.

    */
   void add(E value);
 
   /**
-   * Appends all elements of the [iterable] to the end of this list.
+   * Appends all objects of [iterable] to the end of this list.
    *
-   * Extends the length of the list by the number of elements in [iterable].
-   * Throws an [UnsupportedError] if this list is not extensible.
+   * Extends the length of the list by the number of objects in [iterable].
+   * Throws an [UnsupportedError] if this list is not growable.

[Kathy Walrath, 2013/08/19 22:41:10]

see comment for add()

[mem, 2013/08/20 21:14:07]

Done.

    */
   void addAll(Iterable<E> iterable);
 
   /**
-   * Returns an [Iterable] of the elements of this [List] in reverse order.
+   * Returns an [Iterable] of the objects in this List in reverse order.
    */
   Iterable<E> get reversed;
 
   /**
    * Sorts the list according to the order specified by the [compare] function.
    *
    * The [compare] function must act as a [Comparator].
    *
-   * The default [List] implementations use [Comparable.compare] if
+   * The default List implementations use [Comparable.compare] if
    * [compare] is omitted.
    */
   void sort([int compare(E a, E b)]);
 
   /**
    * Returns the first index of [element] in the list.
    *
    * Searches the list from index [start] to the length of the list.
-   * The first time an element [:e:] is encountered so that [:e == element:],
-   * the index of [:e:] is returned.
+   * The first time an object [:o:] is encountered so that [:o == element:],
+   * the index of [:o:] is returned.
    * Returns -1 if [element] is not found.
    */
   int indexOf(E element, [int start = 0]);
 
   /**
    * Returns the last index of [element] in the list.
    *
-   * Searches the list backwards from index [start] (inclusive) to 0.
+   * Searches the list backwards from index [start] to 0.
    *
-   * The first time an element [:e:] is encountered so that [:e == element:],
-   * the index of [:e:] is returned.
+   * The first time an object [:o:] is encountered so that [:o == element:],
+   * the index of [:o:] is returned.
    *
-   * If start is not provided, it defaults to [:this.length - 1:].
+   * If [start] is not provided, it defaults to [:this.length - 1:].
    *
    * Returns -1 if [element] is not found.
    */
   int lastIndexOf(E element, [int start]);
 
   /**
-   * Removes all elements in the list.
-   *
+   * Removes all objects from the list.
    * The length of the list becomes zero.
    *
-   * Throws an [UnsupportedError], and retains all elements, if the
+   * Throws an [UnsupportedError], and retains all objects, if the
    * length of the list cannot be changed.

[Kathy Walrath, 2013/08/19 22:41:10]

the length... -> this is a fixed-length list

[mem, 2013/08/20 21:14:07]

Done.

    */
   void clear();
 
   /**
-   * Inserts the element at position [index] in the list.
+   * Inserts the object at position [index] in the list.
    *
-   * This increases the length of the list by one and shifts all elements
+   * This increases the length of the list by one and shifts all objects
    * at or after the index towards the end of the list.
    *
-   * It is an error if the [index] does not point inside the list or at the
-   * position after the last element.
+   * An error occurs if the [index] is less than 0 or greater than length.

[Kathy Walrath, 2013/08/19 22:41:10]

isn't there an UnsupportedException if this is a fixed-length list?

[mem, 2013/08/20 21:14:07]

Why yes there is. UnsupportedError.

On 2013/08/19 22:41:10, Kathy Walrath wrote:

    */
   void insert(int index, E element);
 
   /**
-   * Inserts all elements of [iterable] at position [index] in the list.
+   * Inserts all objects of [iterable] at position [index] in the list.
    *
    * This increases the length of the list by the length of [iterable] and
-   * shifts all later elements towards the end of the list.
+   * shifts all later objects towards the end of the list.
    *
-   * It is an error if the [index] does not point inside the list or at the
-   * position after the last element.
+   * An error occurs if the [index] is less than 0 or greater than length.

[Kathy Walrath, 2013/08/19 22:41:10]

isn't there an UnsupportedException if this is a fixed-length list?

[mem, 2013/08/20 21:14:07]

Done.

    */
   void insertAll(int index, Iterable<E> iterable);
 
   /**
-   * Overwrites elements of `this` with the elemenst of [iterable] starting
+   * Overwrites objects of `this` with the objects of [iterable] starting

[Kathy Walrath, 2013/08/19 22:41:10]

 starting -> , starting

[mem, 2013/08/20 21:14:07]

Done.

    * at position [index] in the list.
    *
    * This operation does not increase the length of `this`.
    *
-   * It is an error if the [index] does not point inside the list or at the
-   * position after the last element.
+   * An error occurs if the [index] is less than 0 or greater than length.

[Kathy Walrath, 2013/08/19 22:41:10]

It seems like both errors could go in a single paragraph or be in a bulleted
list.

[mem, 2013/08/20 21:14:07]

Done.

    *
-   * It is an error if the [iterable] is longer than [length] - [index].
+   * An error occurs if the [iterable] is longer than [length] - [index].
    */
   void setAll(int index, Iterable<E> iterable);
 
   /**
    * Removes [value] from the list. Returns true if [value] was

[Kathy Walrath, 2013/08/19 22:41:10]

convert to one-sentence first paragraph.

[mem, 2013/08/20 21:14:07]

Done.

    * in the list. Returns false otherwise. The method has no effect
-   * if [value] value was not in the list.
+   * if [value] was not in the list.
    */
   bool remove(Object value);
 
   /**
-   * Removes the element at position [index] from the list.
+   * Removes the object at position [index] from the list.
    *
-   * This reduces the length of `this` by one and moves all later elements
+   * This reduces the length of `this` by one and moves all later objects

[Kathy Walrath, 2013/08/19 22:41:10]

This -> This method

[mem, 2013/08/20 21:14:08]

Done.

    * down by one position.
    *
-   * Returns the removed element.
+   * Returns the removed object.
    *
    * Throws an [ArgumentError] if [index] is not an [int].

[Kathy Walrath, 2013/08/19 22:41:10]

It seems excessive to have a paragraph per "Throws". Use a bulleted list or
single paragraph instead.

[mem, 2013/08/20 21:14:08]

Done.

    *
-   * Throws an [RangeError] if the [index] does not point inside
-   * the list.
+   * Throws a [RangeError] if the [index] is out of range for this list.
    *
-   * Throws an [UnsupportedError], and doesn't remove the element,
+   * Throws an [UnsupportedError], and doesn't remove the object,
    * if the length of `this` cannot be changed.

[Kathy Walrath, 2013/08/19 22:41:10]

See the "fixed-length" comment for removeLast().

[mem, 2013/08/20 21:14:08]

Done.

    */
   E removeAt(int index);
 
   /**
-   * Pops and returns the last element of the list.
+   * Pops and returns the last object of the list.

[Kathy Walrath, 2013/08/19 22:41:10]

add blank line after this one

[mem, 2013/08/20 21:14:08]

Done.

    * Throws a [UnsupportedError] if the length of the

[Kathy Walrath, 2013/08/19 22:41:10]

a -> an

how about "if the length..." -> "this is a fixed-length list"

[mem, 2013/08/20 21:14:08]

Done.

    * list cannot be changed.
    */
   E removeLast();
 
   /**
-   * Removes all elements of this list that satisfy [test].
+   * Removes all objects from this list that satisfy [test].
    *
-   * An elements [:e:] satisfies [test] if [:test(e):] is true.
+   * An object [:o:] satisfies [test] if [:test(o):] is true.

[Kathy Walrath, 2013/08/19 22:41:10]

Probably throws an UnsupportedError if this is a fixed-length list, no?

[mem, 2013/08/20 21:14:08]

Done.

    */
   void removeWhere(bool test(E element));
 
   /**
-   * Removes all elements of this list that fail to satisfy [test].
+   * Removes all objects from this list that fail to satisfy [test].
    *
-   * An elements [:e:] satisfies [test] if [:test(e):] is true.
+   * An object [:o:] satisfies [test] if [:test(o):] is true.

[Kathy Walrath, 2013/08/19 22:41:10]

Probably throws an UnsupportedError if this is a fixed-length list, no?

[mem, 2013/08/20 21:14:08]

Done.

    */
   void retainWhere(bool test(E element));
 
   /**
-   * Returns a new list containing the elements from [start] to [end].
-   *
-   * The result contains elements of this list with indices greater than or
-   * equal to [start] and less than [end].
+   * Returns a new list containing the objects
+   * from [start] inclusive to [end] exclusive.
    *
    * If [end] is omitted, the [length] of `this` is used.
    *
-   * It is an error if [start] is outside the range `0` .. `[length]` or if
-   * [end] is outside the range `[start]` .. `[length]`.
+   * An error occurs if [start] is outside the range `0` .. `length` or if
+   * [end] is outside the range `start` .. `length`.
    */
   List<E> sublist(int start, [int end]);
 
   /**
-   * Returns an [Iterable] that iterates over the elements in the range
-   * [start] to [end] exclusive. The result of this function
+   * Returns an [Iterable] that iterates over the objects in the range
+   * [start] inclusive to [end] exclusive. The result of this function

[Kathy Walrath, 2013/08/19 22:41:10]

Add blank line before "The result"

[mem, 2013/08/20 21:14:08]

Done.

    * is backed by `this`.

[Kathy Walrath, 2013/08/19 22:41:10]

I don't know what this means.

[mem, 2013/08/20 21:14:08]

Done.

    *
-   * It is an error if [end] is before [start].
+   * An error occurs if [end] is before [start].
    *
-   * It is an error if the [start] and [end] are not valid ranges at the time
+   * 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 similar to

[Kathy Walrath, 2013/08/19 22:41:10]

similar to -> similarly to
OR
-> like

[mem, 2013/08/20 21:14:08]

Done.

    * `skip(start).take(end - start)`. That is, it will not throw exceptions

[Kathy Walrath, 2013/08/19 22:41:10]

will -> does

[mem, 2013/08/20 21:14:08]

Done.

    * if `this` changes size.
    *
    * Example:
    *
    *     var list = [1, 2, 3, 4, 5];
    *     var range = list.getRange(1, 4);
    *     print(range.join(', '));  // => 2, 3, 4
    *     list.length = 3;
    *     print(range.join(', '));  // => 2, 3
    */
   Iterable<E> getRange(int start, int end);
 
   /**
-   * Copies the elements of [iterable], skipping the [skipCount] first elements,
-   * into the range [start] to [end] exclusive of `this`.
+   * Copies the objects of [iterable], skipping [skipCount] objects first,
+   * into the range [start] inclusive to [end] exclusive of `this`.
    *
    * If [start] equals [end] and [start]..[end] represents a legal range, this
    * method has no effect.
    *
-   * It is an error if [start]..[end] is not a valid range pointing into the
-   * `this`.
+   * An error occurs if [start]..[end] is not a valid range for `this`.
    *
-   * It is an error if the [iterable] does not have enough elements after
-   * skipping [skipCount] elements.
+   * An error occurs if the [iterable] does not have enough objects after
+   * skipping [skipCount] objects.
    *
    * Example:
    *
    *     var list = [1, 2, 3, 4];
    *     var list2 = [5, 6, 7, 8, 9];
    *     list.setRange(1, 3, list2, 3);
    *     print(list);  // => [1, 8, 9, 4]
    */
   void setRange(int start, int end, Iterable<E> iterable, [int skipCount = 0]);
 
   /**
-   * Removes the elements in the range [start] to [end] exclusive.
+   * Removes the objects in the range [start] inclusive to [end] exclusive.
    *
-   * It is an error if [start]..[end] is not a valid range pointing into the
-   * `this`.
+   * An error occurs if [start]..[end] is not a valid range for `this`.

[Kathy Walrath, 2013/08/19 22:41:10]

isn't there an UnsupportedException if this is a fixed-length list?

[mem, 2013/08/20 21:14:08]

Done.

    */
   void removeRange(int start, int end);
 
   /**
-   * Sets the elements in the range [start] to [end] exclusive to the given
-   * [fillValue].
+   * Sets the objects in the range [start] inclusive to [end] exclusive
+   * to the given [fillValue].
    *
-   * It is an error if [start]..[end] is not a valid range pointing into the
-   * `this`.
+   * An error occurs if [start]..[end] is not a valid range for `this`.
    */
   void fillRange(int start, int end, [E fillValue]);
 
   /**
-   * Removes the elements in the range [start] to [end] exclusive and replaces
-   * them with the contents of the [iterable].
+   * Removes the objects in the range [start] inclusive to [end] exclusive
+   * and replaces them with the contents of the [iterable].
    *
-   * It is an error if [start]..[end] is not a valid range pointing into the
-   * `this`.
+   * An error occurs if [start]..[end] is not a valid range for `this`.
    *
    * Example:
    *
    *     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. The [Map.keys] [Iterable] will iterate the indices of this list
+   * The map uses the indices of this list as keys and the corresponding objects
+   * as values. The `Map.keys` [Iterable] iterates the indices of this list
    * in numerical order.
    */
   Map<int, E> asMap();
 }