Add documentation to typed-list .fromList constructors saying that values are truncated.

sdk/lib/typed_data/typed_data.dart

Index: sdk/lib/typed_data/typed_data.dart
diff --git a/sdk/lib/typed_data/typed_data.dart b/sdk/lib/typed_data/typed_data.dart
index b04675c693b9f7aa0797727efe8b71b60f00bf2a..2ba5423a13e605797fd18f3a6f6be1ec7817a9e0 100644
--- a/sdk/lib/typed_data/typed_data.dart
+++ b/sdk/lib/typed_data/typed_data.dart
@@ -10,7 +10,7 @@ import 'dart:collection';
 
 /**
  * A sequence of bytes underlying a typed data object.
- * 
+ *
  * Used to process large quantities of binary or numerical data
  * more efficiently using a typed view.
  */
@@ -404,7 +404,7 @@ class Endianness {
  * A fixed-length, random-access sequence of bytes that also provides random
  * and unaligned access to the fixed-width integers and floating point
  * numbers represented by those bytes.
- * 
+ *
  * `ByteData` 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
@@ -451,7 +451,7 @@ abstract class ByteData implements TypedData {
    * Returns the (possibly negative) integer represented by the byte at the
    * specified [byteOffset] in this object, in two's complement binary
    * representation.
-   * 
+   *
    * The return value will be between -128 and 127, inclusive.
    *
    * Throws [RangeError] if [byteOffset] is negative, or
@@ -463,7 +463,7 @@ abstract class ByteData implements TypedData {
    * Sets the byte at the specified [byteOffset] in this object to the
    * two's complement binary representation of the specified [value], which
    * must fit in a single byte.
-   * 
+   *
    * In other words, [value] must be between -128 and 127, inclusive.
    *
    * Throws [RangeError] if [byteOffset] is negative, or
@@ -474,7 +474,7 @@ abstract class ByteData implements TypedData {
   /**
    * Returns the positive integer represented by the byte at the specified
    * [byteOffset] in this object, in unsigned binary form.
-   * 
+   *
    * The return value will be between 0 and 255, inclusive.
    *
    * Throws [RangeError] if [byteOffset] is negative, or
@@ -486,7 +486,7 @@ abstract class ByteData implements TypedData {
    * Sets the byte at the specified [byteOffset] in this object to the
    * unsigned binary representation of the specified [value], which must fit
    * in a single byte.
-   * 
+   *
    * In other words, [value] must be between 0 and 255, inclusive.
    *
    * Throws [RangeError] if [byteOffset] is negative,
@@ -498,7 +498,7 @@ abstract class ByteData implements TypedData {
    * Returns the (possibly negative) integer represented by the two bytes at
    * the specified [byteOffset] in this object, in two's complement binary
    * form.
-   * 
+   *
    * The return value will be between 2<sup>15</sup> and 2<sup>15</sup> - 1,
    * inclusive.
    *
@@ -511,7 +511,7 @@ abstract class ByteData implements TypedData {
    * Sets the two bytes starting at the specified [byteOffset] in this
    * object 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</sup> - 1, inclusive.
    *
@@ -526,7 +526,7 @@ abstract class ByteData implements TypedData {
    * Returns the positive integer represented by the two bytes starting
    * at the specified [byteOffset] in this object, in unsigned binary
    * form.
-   * 
+   *
    * The return value will be between 0 and  2<sup>16</sup> - 1, inclusive.
    *
    * Throws [RangeError] if [byteOffset] is negative, or
@@ -538,7 +538,7 @@ abstract class ByteData implements TypedData {
    * Sets the two bytes starting at the specified [byteOffset] in this object
    * to the unsigned binary representation of the specified [value],
    * which must fit in two bytes.
-   * 
+   *
    * In other words, [value] must be between
    * 0 and 2<sup>16</sup> - 1, inclusive.
    *
@@ -553,7 +553,7 @@ abstract class ByteData implements TypedData {
    * Returns the (possibly negative) integer represented by the four bytes at
    * the specified [byteOffset] in this object, in two's complement binary
    * form.
-   * 
+   *
    * The return value will be between 2<sup>31</sup> and 2<sup>31</sup> - 1,
    * inclusive.
    *
@@ -566,7 +566,7 @@ abstract class ByteData implements TypedData {
    * Sets the four bytes starting at the specified [byteOffset] in this
    * object 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</sup> - 1, inclusive.
    *
@@ -581,7 +581,7 @@ abstract class ByteData implements TypedData {
    * Returns the positive integer represented by the four bytes starting
    * at the specified [byteOffset] in this object, in unsigned binary
    * form.
-   * 
+   *
    * The return value will be between 0 and  2<sup>32</sup> - 1, inclusive.
    *
    * Throws [RangeError] if [byteOffset] is negative, or
@@ -593,7 +593,7 @@ abstract class ByteData implements TypedData {
    * Sets the four bytes starting at the specified [byteOffset] in this object
    * to the unsigned binary representation of the specified [value],
    * which must fit in four bytes.
-   * 
+   *
    * In other words, [value] must be between
    * 0 and 2<sup>32</sup> - 1, inclusive.
    *
@@ -608,7 +608,7 @@ abstract class ByteData implements TypedData {
    * Returns the (possibly negative) integer represented by the eight bytes at
    * the specified [byteOffset] in this object, in two's complement binary
    * form.
-   * 
+   *
    * The return value will be between 2<sup>63</sup> and 2<sup>63</sup> - 1,
    * inclusive.
    *
@@ -621,7 +621,7 @@ abstract class ByteData implements TypedData {
    * Sets the eight bytes starting at the specified [byteOffset] in this
    * object 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</sup> - 1, inclusive.
    *
@@ -636,7 +636,7 @@ abstract class ByteData implements TypedData {
    * Returns the positive integer represented by the eight bytes starting
    * at the specified [byteOffset] in this object, in unsigned binary
    * form.
-   * 
+   *
    * The return value will be between 0 and  2<sup>64</sup> - 1, inclusive.
    *
    * Throws [RangeError] if [byteOffset] is negative, or
@@ -648,7 +648,7 @@ abstract class ByteData implements TypedData {
    * Sets the eight bytes starting at the specified [byteOffset] in this object
    * to the unsigned binary representation of the specified [value],
    * which must fit in eight bytes.
-   * 
+   *
    * In other words, [value] must be between
    * 0 and 2<sup>64</sup> - 1, inclusive.
    *
@@ -718,7 +718,7 @@ abstract class ByteData implements TypedData {
 
 /**
  * A fixed-length list of 8-bit signed integers.
- * 
+ *
  * For long lists, this implementation can be considerably
  * more space- and time-efficient than the default [List] implementation.
  */
@@ -732,6 +732,9 @@ abstract class Int8List implements List<int>, TypedData {
   /**
    * Creates a [Int8List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * Values are truncated to fit in the list when they are copied,
+   * the same way `operator[]` truncates values.

[sra1, 2015/10/26 16:42:22]

operator[]=

Where is this truncation behaviour described?
Can this be phrased to contain a link to that place?

Consider describing the truncation behaviour in the class comment. Otherwise you
need to add abstract members just as somewhere to add documentation (not
necessarily a bad thing).  E.g. the same is true of setRange.

    */
   external factory Int8List.fromList(List<int> elements);
 
@@ -760,7 +763,7 @@ abstract class Int8List implements List<int>, TypedData {
 
 /**
  * A fixed-length list of 8-bit unsigned integers.
- * 
+ *
  * For long lists, this implementation can be considerably
  * more space- and time-efficient than the default [List] implementation.
  */
@@ -774,6 +777,9 @@ abstract class Uint8List implements List<int>, TypedData {
   /**
    * Creates a [Uint8List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * Values are truncated to fit in the list when they are copied,
+   * the same way `operator[]` truncates values.
    */
   external factory Uint8List.fromList(List<int> elements);
 
@@ -802,7 +808,7 @@ abstract class Uint8List implements List<int>, TypedData {
 
 /**
  * A fixed-length list of 8-bit unsigned integers.
- * 
+ *
  * For long lists, this implementation can be considerably
  * more space- and time-efficient than the default [List] implementation.
  * Indexed store clamps the value to range 0..0xFF.
@@ -817,6 +823,9 @@ abstract class Uint8ClampedList implements List<int>, TypedData {
   /**
    * Creates a [Uint8ClampedList] of the same size as the [elements]
    * list and copies over the values clamping when needed.
+   *
+   * Values are clamped to fit in the list when they are copied,
+   * the same way `operator[]` clamps values.
    */
   external factory Uint8ClampedList.fromList(List<int> elements);
 
@@ -847,7 +856,7 @@ abstract class Uint8ClampedList implements List<int>, TypedData {
 /**
  * A fixed-length list of 16-bit signed integers that is viewable as a
  * [TypedData].
- * 
+ *
  * For long lists, this implementation can be considerably
  * more space- and time-efficient than the default [List] implementation.
  */
@@ -861,6 +870,9 @@ abstract class Int16List implements List<int>, TypedData {
   /**
    * Creates a [Int16List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * Values are truncated to fit in the list when they are copied,
+   * the same way `operator[]` truncates values.
    */
   external factory Int16List.fromList(List<int> elements);
 
@@ -893,7 +905,7 @@ abstract class Int16List implements List<int>, TypedData {
 /**
  * A fixed-length list of 16-bit unsigned integers that is viewable as a
  * [TypedData].
- * 
+ *
  * For long lists, this implementation can be considerably
  * more space- and time-efficient than the default [List] implementation.
  */
@@ -907,6 +919,9 @@ abstract class Uint16List implements List<int>, TypedData {
   /**
    * Creates a [Uint16List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * Values are truncated to fit in the list when they are copied,
+   * the same way `operator[]` truncates values.
    */
   external factory Uint16List.fromList(List<int> elements);
 
@@ -940,7 +955,7 @@ abstract class Uint16List implements List<int>, TypedData {
 /**
  * A fixed-length list of 32-bit signed integers that is viewable as a
  * [TypedData].
- * 
+ *
  * For long lists, this implementation can be considerably
  * more space- and time-efficient than the default [List] implementation.
  */
@@ -954,6 +969,9 @@ abstract class Int32List implements List<int>, TypedData {
   /**
    * Creates a [Int32List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * Values are truncated to fit in the list when they are copied,
+   * the same way `operator[]` truncates values.
    */
   external factory Int32List.fromList(List<int> elements);
 
@@ -986,7 +1004,7 @@ abstract class Int32List implements List<int>, TypedData {
 /**
  * A fixed-length list of 32-bit unsigned integers that is viewable as a
  * [TypedData].
- * 
+ *
  * For long lists, this implementation can be considerably
  * more space- and time-efficient than the default [List] implementation.
  */
@@ -1000,6 +1018,9 @@ abstract class Uint32List implements List<int>, TypedData {
   /**
    * Creates a [Uint32List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * Values are truncated to fit in the list when they are copied,
+   * the same way `operator[]` truncates values.
    */
   external factory Uint32List.fromList(List<int> elements);
 
@@ -1033,7 +1054,7 @@ abstract class Uint32List implements List<int>, TypedData {
 /**
  * A fixed-length list of 64-bit signed integers that is viewable as a
  * [TypedData].
- * 
+ *
  * For long lists, this implementation can be considerably
  * more space- and time-efficient than the default [List] implementation.
  */
@@ -1047,6 +1068,9 @@ abstract class Int64List implements List<int>, TypedData {
   /**
    * Creates a [Int64List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * Values are truncated to fit in the list when they are copied,
+   * the same way `operator[]` truncates values.
    */
   external factory Int64List.fromList(List<int> elements);
 
@@ -1079,7 +1103,7 @@ abstract class Int64List implements List<int>, TypedData {
 /**
  * A fixed-length list of 64-bit unsigned integers that is viewable as a
  * [TypedData].
- * 
+ *
  * For long lists, this implementation can be considerably
  * more space- and time-efficient than the default [List] implementation.
  */
@@ -1093,6 +1117,9 @@ abstract class Uint64List implements List<int>, TypedData {
   /**
    * Creates a [Uint64List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * Values are truncated to fit in the list when they are copied,
+   * the same way `operator[]` truncates values.
    */
   external factory Uint64List.fromList(List<int> elements);
 
@@ -1126,7 +1153,7 @@ abstract class Uint64List implements List<int>, TypedData {
 /**
  * A fixed-length list of IEEE 754 single-precision binary floating-point
  * numbers  that is viewable as a [TypedData].
- * 
+ *
  * For long lists, this
  * implementation can be considerably more space- and time-efficient than
  * the default [List] implementation.
@@ -1141,6 +1168,9 @@ abstract class Float32List implements List<double>, TypedData {
   /**
    * Creates a [Float32List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * Values are truncated to fit in the list when they are copied,
+   * the same way `operator[]` truncates values.
    */
   external factory Float32List.fromList(List<double> elements);
 
@@ -1173,7 +1203,7 @@ abstract class Float32List implements List<double>, TypedData {
 /**
  * A fixed-length list of IEEE 754 double-precision binary floating-point
  * numbers  that is viewable as a [TypedData].
- * 
+ *
  * For long lists, this
  * implementation can be considerably more space- and time-efficient than
  * the default [List] implementation.
@@ -1220,7 +1250,7 @@ abstract class Float64List implements List<double>, TypedData {
 /**
  * A fixed-length list of Float32x4 numbers that is viewable as a
  * [TypedData].
- * 
+ *
  * For long lists, this implementation will be considerably more
  * space- and time-efficient than the default [List] implementation.
  */
@@ -1266,7 +1296,7 @@ abstract class Float32x4List implements List<Float32x4>, TypedData {
 /**
  * A fixed-length list of Int32x4 numbers that is viewable as a
  * [TypedData].
- * 
+ *
  * For long lists, this implementation will be considerably more
  * space- and time-efficient than the default [List] implementation.
  */
@@ -1312,7 +1342,7 @@ abstract class Int32x4List implements List<Int32x4>, TypedData {
 /**
  * A fixed-length list of Float64x2 numbers that is viewable as a
  * [TypedData].
- * 
+ *
  * For long lists, this implementation will be considerably more
  * space- and time-efficient than the default [List] implementation.
  */
@@ -1357,7 +1387,7 @@ abstract class Float64x2List implements List<Float64x2>, TypedData {
 
 /**
  * Float32x4 immutable value type and operations.
- * 
+ *
  * Float32x4 stores 4 32-bit floating point values in "lanes".
  * The lanes are "x", "y", "z", and "w" respectively.
  */
@@ -1712,7 +1742,7 @@ abstract class Float32x4 {
 
 /**
  * Int32x4 and operations.
- * 
+ *
  * Int32x4 stores 4 32-bit bit-masks in "lanes".
  * The lanes are "x", "y", "z", and "w" respectively.
  */
@@ -2049,7 +2079,7 @@ abstract class Int32x4 {
 
 /**
  * Float64x2 immutable value type and operations.
- * 
+ *
  * Float64x2 stores 2 64-bit floating point values in "lanes".
  * The lanes are "x" and "y" respectively.
  */