Document the ByteArray types and reconcile with the implementation.

runtime/lib/byte_array.dart

Index: runtime/lib/byte_array.dart
diff --git a/runtime/lib/byte_array.dart b/runtime/lib/byte_array.dart
index 2e0cdeb88c95f7a26e9b017496a0f36f99cdb668..b5a85b175fba9807ada4872cec1b10760623c849 100644
--- a/runtime/lib/byte_array.dart
+++ b/runtime/lib/byte_array.dart
@@ -2,129 +2,680 @@
 // 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 random-access sequence of bytes that also provides random access to
+ * the fixed-width integers and floating point numbers represented by
+ * those bytes. Byte arrays may be used to pack and unpack data from
+ * external sources (such as networks or files systems), and to process
+ * large quantities of numerical data more efficiently than would be possible
+ * with ordinary [List] implementations. Byte arrays can save space, by
+ * eliminating the need for object headers, and time, by eliminating the
+ * need for data copies. Finally, Byte arrays may be used to intentionally
+ * reinterpret the bytes representing one arithmetic type as another.
+ * For example this code fragment determine what 64-bit signed integer
+ * is represented by the bytes of a 64-bit floating point number:
+ *
+ *    var ba = new ByteArray(8);
+ *    ba.setFloat64(0, 3.14159265358979323846);
+ *    int huh = ba.getInt64(0);
+ */
 interface ByteArray {
+  /**
+   * Returns the length of this byte array, in bytes.
+   */
   int lengthInBytes();
 
+  /**
+   * Returns a [ByteArray] _view_ of a portion of this byte array.
+   * The returned byte array consists of [length] bytes starting
+   * at position [start] in this byte array. The returned byte array
+   * is backed by the same data as this byte array. In other words,
+   * changes to the returned byte array are visible in this byte array
+   * and vice-versa.
+   *
+   * Throws [IndexOutOfRangeException] if [start] is negative, or if
+   * `start + length` is greater than the length of this byte array.
+   *
+   * Throws [IllegalArgumentException] if [length] is negative.
+   */
   ByteArray subByteArray([int start, int length]);
 
+  /**
+   * Returns the (possibly negative) integer represented by the byte at the
+   * specified [byteOffset] in this byte array, in two's complement binary
+   * representation. The return value will be between -128 and 127, inclusive.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * greater than or equal to the length of this byte array.
+   */
   int getInt8(int byteOffset);
 
-  void setInt8(int byteOffset, int value);
-
+  /**
+   * Sets the byte at the specified [byteOffset] in this byte array to the
+   * two's complement binary representation of the specified [value], which
+   * must fit in a single byte. In other words, [value] must lie between
+   * -128 and 127, inclusive.

[siva, 2012/06/15 01:52:47]

must be between -128 and 127 may be more readable.

(here and other places below).

[cshapiro, 2012/06/15 20:13:20]

You are suggesting that "lie" be substituted for "be", right?  If so, it has
been fixed.

[cshapiro, 2012/06/15 20:13:20]

I assume you mean to substitute "be" for "lie", right?  If so, it is now fixed.

+   *
+   * Returns `byteOffset + 1`, which is the offset of the first byte in the
+   * array after the byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * greater than or equal to the length of this byte array.
+   *
+   * Throws [IllegalArgumentException] if [value] is less than -128 or
+   * greater than 127.
+   */
+  int setInt8(int byteOffset, int value);
+
+  /**
+   * Returns the positive integer represented by the byte at the specified
+   * [byteOffset] in this byte array, in unsigned binary form. The
+   * return value will be between 0 and 255, inclusive.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * greater than or equal to the length of this byte array.
+   */
   int getUint8(int byteOffset);
 
-  void setUint8(int byteOffset, int value);
-
+  /**
+   * Sets the byte at the specified [byteOffset] in this byte array to the
+   * unsigned binary representation of the specified [value], which must fit
+   * in a single byte. in other words, [value] must lie between 0 and 255,
+   * inclusive.
+   *
+   * Returns `byteOffset + 1`, which is the offset of the first byte in the
+   * array after the byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative,
+   * or greater than or equal to the length of this byte array.
+   *
+   * Throws [IllegalArgumentException] if [value] is negative or
+   * greater than 255.
+   */
+  int setUint8(int byteOffset, int value);
+
+  /**
+   * Returns the (possibly negative) integer represented by the two bytes at
+   * the specified [byteOffset] in this byte array, in two's complement binary
+   * form. The return value will be between 2<sup>15</sup> and 2<sup>15 - 1,
+   * inclusive.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this byte array.
+   */
   int getInt16(int byteOffset);
 
-  void setInt16(int byteOffset, int value);
-
+  /**
+   * Sets the two bytes starting at the specified [byteOffset] in this
+   * byte array to the two's complement binary representation of the specified
+   * [value], which must fit in two bytes. In other words, [value] must lie
+   * between 2<sup>15</sup> and 2<sup>15 - 1, inclusive.
+   *
+   * Returns `byteOffset + 2`, which is the offset of the first byte in the
+   * array after the last byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this byte array.
+   *
+   * Throws [IllegalArgumentException] if [value] is less than 2<sup>15</sup>
+   * or greater than 2<sup>15 - 1,

[siva, 2012/06/15 01:52:47]

comment ends with a ' instead of a .

[cshapiro, 2012/06/15 20:13:20]

I assume you mean ',' instead of '.', right?  If so, it is now fixed.

+   */
+  int setInt16(int byteOffset, int value);
+
+  /**
+   * Returns the positive integer represented by the two bytes starting
+   * at the specified [byteOffset] in this byte array, in unsigned binary
+   * form. The return value will be between 0 and  2<sup>16 - 1, inclusive.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this byte array.
+   */
   int getUint16(int byteOffset);
 
-  void setUint16(int byteOffset, int value);
-
+  /**
+   * Sets the two bytes starting at the specified [byteOffset] in this byte
+   * array to the unsigned binary representation of the specified [value],
+   * which must fit in two bytes. in other words, [value] must lie between
+   * 0 and 2<sup>16 - 1, inclusive.
+   *
+   * Returns `byteOffset + 2`, which is the offset of the first byte in the
+   * array after the last byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 2` is greater than the length of this byte array.
+   *
+   * Throws [IllegalArgumentException] if [value] is negative or
+   * greater than 2<sup>16 - 1.
+   */
+  int setUint16(int byteOffset, int value);
+
+  /**
+   * Returns the (possibly negative) integer represented by the four bytes at
+   * the specified [byteOffset] in this byte array, in two's complement binary
+   * form. The return value will be between 2<sup>31</sup> and 2<sup>31 - 1,
+   * inclusive.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this byte array.
+   */
   int getInt32(int byteOffset);
 
-  void setInt32(int byteOffset, int value);
-
+  /**
+   * Sets the four bytes starting at the specified [byteOffset] in this
+   * byte array to the two's complement binary representation of the specified
+   * [value], which must fit in four bytes. In other words, [value] must lie
+   * between 2<sup>31</sup> and 2<sup>31 - 1, inclusive.
+   *
+   * Returns `byteOffset + 4`, which is the offset of the first byte in the
+   * array after the last byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this byte array.
+   *
+   * Throws [IllegalArgumentException] if [value] is less than 2<sup>31</sup>
+   * or greater than 2<sup>31 - 1,

[siva, 2012/06/15 01:52:47]

Ditto.

[cshapiro, 2012/06/15 20:13:20]

Done.

+   */
+  int setInt32(int byteOffset, int value);
+
+  /**
+   * Returns the positive integer represented by the four bytes starting
+   * at the specified [byteOffset] in this byte array, in unsigned binary
+   * form. The return value will be between 0 and  2<sup>32 - 1, inclusive.
+   *
+   */
   int getUint32(int byteOffset);
 
-  void setUint32(int byteOffset, int value);
-
+  /**
+   * Sets the four bytes starting at the specified [byteOffset] in this byte
+   * array to the unsigned binary representation of the specified [value],
+   * which must fit in four bytes. in other words, [value] must lie between
+   * 0 and 2<sup>32 - 1, inclusive.
+   *
+   * Returns `byteOffset + 4`, which is the offset of the first byte in the
+   * array after the last byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this byte array.
+   *
+   * Throws [IllegalArgumentException] if [value] is negative or
+   * greater than 2<sup>32 - 1.
+   */
+  int setUint32(int byteOffset, int value);
+
+  /**
+   * Returns the (possibly negative) integer represented by the eight bytes at
+   * the specified [byteOffset] in this byte array, in two's complement binary
+   * form. The return value will be between 2<sup>63</sup> and 2<sup>63 - 1,
+   * inclusive.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this byte array.
+   */
   int getInt64(int byteOffset);
 
-  void setInt64(int byteOffset, int value);
-
+  /**
+   * Sets the eight bytes starting at the specified [byteOffset] in this
+   * byte array to the two's complement binary representation of the specified
+   * [value], which must fit in eight bytes. In other words, [value] must lie
+   * between 2<sup>63</sup> and 2<sup>63 - 1, inclusive.
+   *
+   * Returns `byteOffset + 8`, which is the offset of the first byte in the
+   * array after the last byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this byte array.
+   *
+   * Throws [IllegalArgumentException] if [value] is less than 2<sup>63</sup>
+   * or greater than 2<sup>63 - 1,

[siva, 2012/06/15 01:52:47]

Ditto

[cshapiro, 2012/06/15 20:13:20]

Done.

+   */
+  int setInt64(int byteOffset, int value);
+
+  /**
+   * Returns the positive integer represented by the eight bytes starting
+   * at the specified [byteOffset] in this byte array, in unsigned binary
+   * form. The return value will be between 0 and  2<sup>64 - 1, inclusive.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this byte array.
+   */
   int getUint64(int byteOffset);
 
-  void setUint64(int byteOffset, int value);
-
+  /**
+   * Sets the eight bytes starting at the specified [byteOffset] in this byte
+   * array to the unsigned binary representation of the specified [value],
+   * which must fit in eight bytes. in other words, [value] must lie between
+   * 0 and 2<sup>64 - 1, inclusive.
+   *
+   * Returns `byteOffset + 8`, which is the offset of the first byte in the
+   * array after the last byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this byte array.
+   *
+   * Throws [IllegalArgumentException] if [value] is negative or
+   * greater than 2<sup>64 - 1.
+   */
+  int setUint64(int byteOffset, int value);
+
+  /**
+   * Returns the floating point number represented by the four bytes at
+   * the specified [byteOffset] in this byte array, in IEEE 754
+   * single-precision binary floating-point format (binary32).
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this byte array.
+   */
   double getFloat32(int byteOffset);
 
-  void setFloat32(int byteOffset, double value);
-
+  /**
+   * Sets the four bytes starting at the specified [byteOffset] in this
+   * byte array to the IEEE 754 single-precision binary floating-point
+   * (binary32) representation of the specified [value].
+   *
+   * **Note that this method can lose precision.** The input [value] is
+   * a 64-bit floating point value, which will be converted to 32-bit
+   * floating point value by IEEE 754 rounding rules before it is stored.
+   * If [value] cannot be represented exactly as a binary32, it will be
+   * converted to the nearest binary32 value.  If two binary32 values are
+   * equally close, the one whose least significant bit is zero will be used.
+   * Note that finite (but large) values can be converted to infinity, and
+   * small non-zero values can be converted to zero.
+   *
+   * Returns `byteOffset + 4`, which is the offset of the first byte in the
+   * array after the last byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 4` is greater than the length of this byte array.
+   */
+  int setFloat32(int byteOffset, double value);
+
+  /**
+   * Returns the floating point number represented by the eight bytes at
+   * the specified [byteOffset] in this byte array, in IEEE 754
+   * double-precision binary floating-point format (binary64).
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this byte array.
+   */
   double getFloat64(int byteOffset);
 
-  void setFloat64(int byteOffset, double value);
-}
-
-
+  /**
+   * Sets the eight bytes starting at the specified [byteOffset] in this
+   * byte array to the IEEE 754 double-precision binary floating-point
+   * (binary64) representation of the specified [value].
+   *
+   * Returns `byteOffset + 8`, which is the offset of the first byte in the
+   * array after the last byte that was set by this call. This return value can
+   * be passed as the [byteOffset] parameter to a subsequent `setXxx` call.
+   *
+   * Throws [IndexOutOfRangeException] if [byteOffset] is negative, or
+   * `byteOffset + 8` is greater than the length of this byte array.
+   */
+  int setFloat64(int byteOffset, double value);
+}
+
+/**
+ * A "mixin" interface that allows a type, typically but not necessarily
+ * a [List], to be viewed as a [ByteArray].
+ */
 interface ByteArrayViewable {
+  /**
+   * Returns the number of bytes in the representation of each element in
+   * this list, or the number bytes in the representation of the entire
+   * object if it is not a list.
+   */
   int bytesPerElement();
 
+  /**
+   * Returns the length of this view, in bytes.
+   */
   int lengthInBytes();
 
+  /**
+   * Returns the byte array view of this object. This view allows the
+   * byte representation of the object to be read and written directly.
+   */
   ByteArray asByteArray([int start, int length]);
 }
 
 
+/**
+ * A fixed-length list of 8-bit signed integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 interface Int8List extends List<int>, ByteArrayViewable
     default _Int8ArrayFactory {
+  /**
+   * Creates an [Int8List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   Int8List(int length);
+
+  /**
+   * Creates an [Int8List] _view_ of the specified region in the specified
+   * byte [array]. Changes in the [Int8List] will be visible in the byte
+   * array and vice versa. If the [start] index of the region is not specified,
+   * it defaults to zero (the first byte in the byte array). If the length is
+   * not specified, it defaults to null, which indicates that the view extends
+   * to the end of the byte array.
+   */
   Int8List.view(ByteArray array, [int start, int length]);
 }
 
 
+/**
+ * A fixed-length list of 8-bit unsigned integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 interface Uint8List extends List<int>, ByteArrayViewable
     default _Uint8ArrayFactory {
+  /**
+   * Creates a [Uint8List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   Uint8List(int length);
+
+  /**
+   * Creates a [Uint8List] _view_ of the specified region in the specified
+   * byte [array]. Changes in the [Uint8List] will be visible in the byte
+   * array and vice versa. If the [start] index of the region is not specified,
+   * it defaults to zero (the first byte in the byte array). If the length is
+   * not specified, it defaults to null, which indicates that the view extends
+   * to the end of the byte array.
+   */
   Uint8List.view(ByteArray array, [int start, int length]);
 }
 
 
+/**
+ * A fixed-length list of 16-bit signed integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 interface Int16List extends List<int>, ByteArrayViewable
     default _Int16ArrayFactory {
+  /**
+   * Creates an [Int16List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   Int16List(int length);
+
+  /**
+   * Creates an [Int16List] _view_ of the specified region in the specified
+   * byte [array]. Changes in the [Int16List] will be visible in the byte
+   * array and vice versa. If the [start] index of the region is not specified,
+   * it defaults to zero (the first byte in the byte array). If the length is
+   * not specified, it defaults to null, which indicates that the view extends
+   * to the end of the byte array.
+   *
+   * Throws [IllegalArgumentException] if the length of the specified region
+   * is not divisible by 2 (the size of an "int16" in bytes), or if the
+   * [start] of the region is not divisible by 2. If, however, [array]
+   * is a view of another byte array, this constructor will throw
+   * [IllegalArgumentException] if the implicit starting position in the
+   * "ultimately backing" byte array is not divisible by 2. In plain terms,
+   * this constructor throws [IllegalArgumentException] if the specified
+   * region does not contain an integral number of "int16s," or if it
+   * is not "int16-aligned."
+   */
   Int16List.view(ByteArray array, [int start, int length]);
 }
 
 
+/**
+ * A fixed-length list of 16-bit unsigned integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 interface Uint16List extends List<int>, ByteArrayViewable
     default _Uint16ArrayFactory {
+  /**
+   * Creates a [Uint16List] of the specified length (in elements), all
+   * of whose elements are initially zero.
+   */
   Uint16List(int length);
+
+  /**
+   * Creates a [Uint16List] _view_ of the specified region in
+   * the specified byte [array]. Changes in the [Uint16List] will be
+   * visible in the byte array and vice versa. If the [start] index of the
+   * region is not specified, it defaults to zero (the first byte in the byte
+   * array). If the length is not specified, it defaults to null, which
+   * indicates that the view extends to the end of the byte array.
+   *
+   * Throws [IllegalArgumentException] if the length of the specified region
+   * is not divisible by 2 (the size of a "uint16" in bytes), or if the
+   * [start] of the region is not divisible by 2. If, however, [array]
+   * is a view of another byte array, this constructor will throw
+   * [IllegalArgumentException] if the implicit starting position in the
+   * "ultimately backing" byte array is not divisible by 2. In plain terms,
+   * this constructor throws [IllegalArgumentException] if the specified
+   * region does not contain an integral number of "uint16s," or if it
+   * is not "uint16-aligned."
+   */
   Uint16List.view(ByteArray array, [int start, int length]);
 }
 
 
+/**
+ * A fixed-length list of 32-bit signed integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 interface Int32List extends List<int>, ByteArrayViewable
     default _Int32ArrayFactory {
+  /**
+   * Creates an [Int32List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   Int32List(int length);
+
+  /**
+   * Creates an [Int32List] _view_ of the specified region in the specified
+   * byte [array]. Changes in the [Int32List] will be visible in the byte
+   * array and vice versa. If the [start] index of the region is not specified,
+   * it defaults to zero (the first byte in the byte array). If the length is
+   * not specified, it defaults to null, which indicates that the view extends
+   * to the end of the byte array.
+   *
+   * Throws [IllegalArgumentException] if the length of the specified region
+   * is not divisible by 4 (the size of an "int32" in bytes), or if the
+   * [start] of the region is not divisible by 4. If, however, [array]
+   * is a view of another byte array, this constructor will throw
+   * [IllegalArgumentException] if the implicit starting position in the
+   * "ultimately backing" byte array is not divisible by 4. In plain terms,
+   * this constructor throws [IllegalArgumentException] if the specified
+   * region does not contain an integral number of "int32s," or if it
+   * is not "int32-aligned."
+   */
   Int32List.view(ByteArray array, [int start, int length]);
 }
 
 
+/**
+ * A fixed-length list of 32-bit unsigned integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 interface Uint32List extends List<int>, ByteArrayViewable
     default _Uint32ArrayFactory {
+  /**
+   * Creates a [Uint32List] of the specified length (in elements), all
+   * of whose elements are initially zero.
+   */
   Uint32List(int length);
-  Uint32List.view(ByteArray array, [int start, int length]);
 
+  /**
+   * Creates a [Uint32List] _view_ of the specified region in
+   * the specified byte [array]. Changes in the [Uint32] will be
+   * visible in the byte array and vice versa. If the [start] index of the
+   * region is not specified, it defaults to zero (the first byte in the byte
+   * array). If the length is not specified, it defaults to null, which
+   * indicates that the view extends to the end of the byte array.
+   *
+   * Throws [IllegalArgumentException] if the length of the specified region
+   * is not divisible by 4 (the size of a "uint32" in bytes), or if the
+   * [start] of the region is not divisible by 4. If, however, [array]
+   * is a view of another byte array, this constructor will throw
+   * [IllegalArgumentException] if the implicit starting position in the
+   * "ultimately backing" byte array is not divisible by 4. In plain terms,
+   * this constructor throws [IllegalArgumentException] if the specified
+   * region does not contain an integral number of "uint32s," or if it
+   * is not "uint32-aligned."
+   */
+  Uint32List.view(ByteArray array, [int start, int length]);
 }
 
 
+/**
+ * A fixed-length list of 64-bit signed integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 interface Int64List extends List<int>, ByteArrayViewable
     default _Int64ArrayFactory {
+  /**
+   * Creates an [Int64List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   Int64List(int length);
+
+  /**
+   * Creates an [Int64List] _view_ of the specified region in the specified
+   * byte [array]. Changes in the [Int64List] will be visible in the byte
+   * array and vice versa. If the [start] index of the region is not specified,
+   * it defaults to zero (the first byte in the byte array). If the length is
+   * not specified, it defaults to null, which indicates that the view extends
+   * to the end of the byte array.
+   *
+   * Throws [IllegalArgumentException] if the length of the specified region
+   * is not divisible by 8 (the size of an "int64" in bytes), or if the
+   * [start] of the region is not divisible by 8. If, however, [array]
+   * is a view of another byte array, this constructor will throw
+   * [IllegalArgumentException] if the implicit starting position in the
+   * "ultimately backing" byte array is not divisible by 8. In plain terms,
+   * this constructor throws [IllegalArgumentException] if the specified
+   * region does not contain an integral number of "int64s," or if it
+   * is not "int64-aligned."
+   */
   Int64List.view(ByteArray array, [int start, int length]);
 }
 
 
+/**
+ * A fixed-length list of 64-bit unsigned integers that is viewable as a
+ * [ByteArray]. For long lists, this implementation will be considerably
+ * more space- and time-efficient than the default [List] implementation.
+ */
 interface Uint64List extends List<int>, ByteArrayViewable
     default _Uint64ArrayFactory {
+  /**
+   * Creates a [Uint64List] of the specified length (in elements), all
+   * of whose elements are initially zero.
+   */
   Uint64List(int length);
+
+  /**
+   * Creates an [Uint64List] _view_ of the specified region in
+   * the specified byte [array]. Changes in the [Uint64List] will be
+   * visible in the byte array and vice versa. If the [start] index of the
+   * region is not specified, it defaults to zero (the first byte in the byte
+   * array). If the length is not specified, it defaults to null, which
+   * indicates that the view extends to the end of the byte array.
+   *
+   * Throws [IllegalArgumentException] if the length of the specified region
+   * is not divisible by 8 (the size of a "uint64" in bytes), or if the
+   * [start] of the region is not divisible by 8. If, however, [array]
+   * is a view of another byte array, this constructor will throw
+   * [IllegalArgumentException] if the implicit starting position in the
+   * "ultimately backing" byte array is not divisible by 8. In plain terms,
+   * this constructor throws [IllegalArgumentException] if the specified
+   * region does not contain an integral number of "uint64s," or if it
+   * is not "uint64-aligned."
+   */
   Uint64List.view(ByteArray array, [int start, int length]);
 }
 
 
+/**
+ * A fixed-length list of IEEE 754 single-precision binary floating-point
+ * numbers  that is viewable as a [ByteArray]. For long lists, this
+ * implementation will be considerably more space- and time-efficient than
+ * the default [List] implementation.
+ */
 interface Float32List extends List<double>, ByteArrayViewable
     default _Float32ArrayFactory {
+  /**
+   * Creates a [Float32List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   Float32List(int length);
+
+  /**
+   * Creates a [Float32List] _view_ of the specified region in the specified
+   * byte [array]. Changes in the [Float32List] will be visible in the byte
+   * array and vice versa. If the [start] index of the region is not specified,
+   * it defaults to zero (the first byte in the byte array). If the length is
+   * not specified, it defaults to null, which indicates that the view extends
+   * to the end of the byte array.
+   *
+   * Throws [IllegalArgumentException] if the length of the specified region
+   * is not divisible by 4 (the size of a "float32" in bytes), or if the
+   * [start] of the region is not divisible by 4. If, however, [array]
+   * is a view of another byte array, this constructor will throw
+   * [IllegalArgumentException] if the implicit starting position in the
+   * "ultimately backing" byte array is not divisible by 4. In plain terms,
+   * this constructor throws [IllegalArgumentException] if the specified
+   * region does not contain an integral number of "float32s," or if it
+   * is not "float32-aligned."
+   */
   Float32List.view(ByteArray array, [int start, int length]);
 }
 
 
+/**
+ * A fixed-length list of IEEE 754 double-precision binary floating-point
+ * numbers  that is viewable as a [ByteArray]. For long lists, this
+ * implementation will be considerably more space- and time-efficient than
+ * the default [List] implementation.
+ */
 interface Float64List extends List<double>, ByteArrayViewable
     default _Float64ArrayFactory {
+  /**
+   * Creates a [Float64List] of the specified length (in elements), all of
+   * whose elements are initially zero.
+   */
   Float64List(int length);
+
+  /**
+   * Creates a [Float64List] _view_ of the specified region in the specified
+   * byte [array]. Changes in the [Float64List] will be visible in the byte
+   * array and vice versa. If the [start] index of the region is not specified,
+   * it defaults to zero (the first byte in the byte array). If the length is
+   * not specified, it defaults to null, which indicates that the view extends
+   * to the end of the byte array.
+   *
+   * Throws [IllegalArgumentException] if the length of the specified region
+   * is not divisible by 8 (the size of a "float64" in bytes), or if the
+   * [start] of the region is not divisible by 8. If, however, [array]
+   * is a view of another byte array, this constructor will throw
+   * [IllegalArgumentException] if the implicit starting position in the
+   * "ultimately backing" byte array is not divisible by 8. In plain terms,
+   * this constructor throws [IllegalArgumentException] if the specified
+   * region does not contain an integral number of "float64s," or if it
+   * is not "float64-aligned."
+   */
   Float64List.view(ByteArray array, [int start, int length]);
 }
 
@@ -349,34 +900,34 @@ abstract class _ByteArrayBase {
       native "ByteArray_setRange";
 
   int _getInt8(int byteOffset) native "ByteArray_getInt8";
-  void _setInt8(int byteOffset, int value) native "ByteArray_setInt8";
+  int _setInt8(int byteOffset, int value) native "ByteArray_setInt8";
 
   int _getUint8(int byteOffset) native "ByteArray_getUint8";
-  void _setUint8(int byteOffset, int value) native "ByteArray_setUint8";
+  int _setUint8(int byteOffset, int value) native "ByteArray_setUint8";
 
   int _getInt16(int byteOffset) native "ByteArray_getInt16";
-  void _setInt16(int byteOffset, int value) native "ByteArray_setInt16";
+  int _setInt16(int byteOffset, int value) native "ByteArray_setInt16";
 
   int _getUint16(int byteOffset) native "ByteArray_getUint16";
-  void _setUint16(int byteOffset, int value) native "ByteArray_setUint16";
+  int _setUint16(int byteOffset, int value) native "ByteArray_setUint16";
 
   int _getInt32(int byteOffset) native "ByteArray_getInt32";
-  void _setInt32(int byteOffset, int value) native "ByteArray_setInt32";
+  int _setInt32(int byteOffset, int value) native "ByteArray_setInt32";
 
   int _getUint32(int byteOffset) native "ByteArray_getUint32";
-  void _setUint32(int byteOffset, int value) native "ByteArray_setUint32";
+  int _setUint32(int byteOffset, int value) native "ByteArray_setUint32";
 
   int _getInt64(int byteOffset) native "ByteArray_getInt64";
-  void _setInt64(int byteOffset, int value) native "ByteArray_setInt64";
+  int _setInt64(int byteOffset, int value) native "ByteArray_setInt64";
 
   int _getUint64(int byteOffset) native "ByteArray_getUint64";
-  void _setUint64(int byteOffset, int value) native "ByteArray_setUint64";
+  int _setUint64(int byteOffset, int value) native "ByteArray_setUint64";
 
   double _getFloat32(int byteOffset) native "ByteArray_getFloat32";
-  void _setFloat32(int byteOffset, double value) native "ByteArray_setFloat32";
+  int _setFloat32(int byteOffset, double value) native "ByteArray_setFloat32";
 
   double _getFloat64(int byteOffset) native "ByteArray_getFloat64";
-  void _setFloat64(int byteOffset, double value) native "ByteArray_setFloat64";
+  int _setFloat64(int byteOffset, double value) native "ByteArray_setFloat64";
 }