Update typed-data constructor documentation.

Make it explicit that the allocating constructors allocate precisly the
needed amount of bytes.

Fixes #40261

Bug: http://dartbug.com/40261
Change-Id: I059a9e3e387fee116e2221a0761557aedc948aee
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/132844
Commit-Queue: Lasse R.H. Nielsen <[email protected]>
Reviewed-by: Martin Kustermann <[email protected]>

Author: lrhn

sdk/lib/typed_data/typed_data.dart

@@ -445,12 +445,12 @@ class Endian {
  * Finally, `ByteData` may be used to intentionally reinterpret the bytes
  * representing one arithmetic type as another.
  * For example this code fragment determine what 32-bit signed integer
- * is represented by the bytes of a 32-bit floating point number:
+ * is represented by the bytes of a 32-bit floating point number
+ * (both stored as big endian):
  *
- *     var buffer = new Uint8List(8).buffer;
- *     var bdata = new ByteData.view(buffer);
+ *     var bdata = new ByteData(8);
  *     bdata.setFloat32(0, 3.04);
- *     int huh = bdata.getInt32(0);
+ *     int huh = bdata.getInt32(0); // 0x40428f5c
  */
 abstract class ByteData implements TypedData {
   /**
@@ -787,6 +787,8 @@ abstract class Int8List implements List<int>, _TypedIntList {
   /**
    * Creates an [Int8List] of the specified length (in elements), all of
    * whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely [length] bytes.
    */
   external factory Int8List(int length);
 
@@ -796,6 +798,9 @@ abstract class Int8List implements List<int>, _TypedIntList {
    *
    * Values are truncated to fit in the list when they are copied,
    * the same way storing values truncates them.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely `elements.length`
+   * bytes.
    */
   external factory Int8List.fromList(List<int> elements);
 
@@ -904,6 +909,8 @@ abstract class Uint8List implements List<int>, _TypedIntList {
   /**
    * Creates a [Uint8List] of the specified length (in elements), all of
    * whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely [length] bytes.
    */
   external factory Uint8List(int length);
 
@@ -913,6 +920,9 @@ abstract class Uint8List implements List<int>, _TypedIntList {
    *
    * Values are truncated to fit in the list when they are copied,
    * the same way storing values truncates them.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely `elements.length`
+   * bytes.
    */
   external factory Uint8List.fromList(List<int> elements);
 
@@ -1030,6 +1040,8 @@ abstract class Uint8ClampedList implements List<int>, _TypedIntList {
   /**
    * Creates a [Uint8ClampedList] of the specified length (in elements), all of
    * whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely [length] bytes.
    */
   external factory Uint8ClampedList(int length);
 
@@ -1039,6 +1051,9 @@ abstract class Uint8ClampedList implements List<int>, _TypedIntList {
    *
    * Values are clamped to fit in the list when they are copied,
    * the same way storing values clamps them.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely `elements.length`
+   * bytes.
    */
   external factory Uint8ClampedList.fromList(List<int> elements);
 
@@ -1150,6 +1165,9 @@ abstract class Int16List implements List<int>, _TypedIntList {
   /**
    * Creates an [Int16List] of the specified length (in elements), all of
    * whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 2 bytes.
    */
   external factory Int16List(int length);
 
@@ -1159,6 +1177,9 @@ abstract class Int16List implements List<int>, _TypedIntList {
    *
    * Values are truncated to fit in the list when they are copied,
    * the same way storing values truncates them.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 2 bytes.
    */
   external factory Int16List.fromList(List<int> elements);
 
@@ -1279,6 +1300,9 @@ abstract class Uint16List implements List<int>, _TypedIntList {
   /**
    * Creates a [Uint16List] of the specified length (in elements), all
    * of whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 2 bytes.
    */
   external factory Uint16List(int length);
 
@@ -1288,6 +1312,9 @@ abstract class Uint16List implements List<int>, _TypedIntList {
    *
    * Values are truncated to fit in the list when they are copied,
    * the same way storing values truncates them.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 2 bytes.
    */
   external factory Uint16List.fromList(List<int> elements);
 
@@ -1409,6 +1436,9 @@ abstract class Int32List implements List<int>, _TypedIntList {
   /**
    * Creates an [Int32List] of the specified length (in elements), all of
    * whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 4 bytes.
    */
   external factory Int32List(int length);
 
@@ -1418,6 +1448,9 @@ abstract class Int32List implements List<int>, _TypedIntList {
    *
    * Values are truncated to fit in the list when they are copied,
    * the same way storing values truncates them.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 4 bytes.
    */
   external factory Int32List.fromList(List<int> elements);
 
@@ -1538,6 +1571,9 @@ abstract class Uint32List implements List<int>, _TypedIntList {
   /**
    * Creates a [Uint32List] of the specified length (in elements), all
    * of whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 4 bytes.
    */
   external factory Uint32List(int length);
 
@@ -1547,6 +1583,9 @@ abstract class Uint32List implements List<int>, _TypedIntList {
    *
    * Values are truncated to fit in the list when they are copied,
    * the same way storing values truncates them.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 4 bytes.
    */
   external factory Uint32List.fromList(List<int> elements);
 
@@ -1668,6 +1707,9 @@ abstract class Int64List implements List<int>, _TypedIntList {
   /**
    * Creates an [Int64List] of the specified length (in elements), all of
    * whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 8 bytes.
    */
   external factory Int64List(int length);
 
@@ -1677,6 +1719,9 @@ abstract class Int64List implements List<int>, _TypedIntList {
    *
    * Values are truncated to fit in the list when they are copied,
    * the same way storing values truncates them.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 8 bytes.
    */
   external factory Int64List.fromList(List<int> elements);
 
@@ -1797,6 +1842,9 @@ abstract class Uint64List implements List<int>, _TypedIntList {
   /**
    * Creates a [Uint64List] of the specified length (in elements), all
    * of whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 8 bytes.
    */
   external factory Uint64List(int length);
 
@@ -1806,6 +1854,9 @@ abstract class Uint64List implements List<int>, _TypedIntList {
    *
    * Values are truncated to fit in the list when they are copied,
    * the same way storing values truncates them.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 8 bytes.
    */
   external factory Uint64List.fromList(List<int> elements);
 
@@ -1928,6 +1979,9 @@ abstract class Float32List implements List<double>, _TypedFloatList {
   /**
    * Creates a [Float32List] of the specified length (in elements), all of
    * whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 4 bytes.
    */
   external factory Float32List(int length);
 
@@ -1937,6 +1991,9 @@ abstract class Float32List implements List<double>, _TypedFloatList {
    *
    * Values are truncated to fit in the list when they are copied,
    * the same way storing values truncates them.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 4 bytes.
    */
   external factory Float32List.fromList(List<double> elements);
 
@@ -2054,12 +2111,18 @@ abstract class Float64List implements List<double>, _TypedFloatList {
   /**
    * Creates a [Float64List] of the specified length (in elements), all of
    * whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 8 bytes.
    */
   external factory Float64List(int length);
 
   /**
    * Creates a [Float64List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 8 bytes.
    */
   external factory Float64List.fromList(List<double> elements);
 
@@ -2176,12 +2239,18 @@ abstract class Float32x4List implements List<Float32x4>, TypedData {
   /**
    * Creates a [Float32x4List] of the specified length (in elements),
    * all of whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 16 bytes.
    */
   external factory Float32x4List(int length);
 
   /**
    * Creates a [Float32x4List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 16 bytes.
    */
   external factory Float32x4List.fromList(List<Float32x4> elements);
 
@@ -2306,12 +2375,18 @@ abstract class Int32x4List implements List<Int32x4>, TypedData {
   /**
    * Creates a [Int32x4List] of the specified length (in elements),
    * all of whose elements are initially zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 16 bytes.
    */
   external factory Int32x4List(int length);
 
   /**
    * Creates a [Int32x4List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 16 bytes.
    */
   external factory Int32x4List.fromList(List<Int32x4> elements);
 
@@ -2436,12 +2511,18 @@ abstract class Float64x2List implements List<Float64x2>, TypedData {
   /**
    * Creates a [Float64x2List] of the specified length (in elements),
    * all of whose elements have all lanes set to zero.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * [length] times 16 bytes.
    */
   external factory Float64x2List(int length);
 
   /**
    * Creates a [Float64x2List] with the same length as the [elements] list
    * and copies over the elements.
+   *
+   * The list is backed by a [ByteBuffer] containing precisely
+   * `elements.length` times 16 bytes.
    */
   external factory Float64x2List.fromList(List<Float64x2> elements);