Document that writeAsBytes truncates values beyond 0..255

Closes dart-lang#53782

GitOrigin-RevId: 5453268
Change-Id: I7804cbe65c93bc34f56db6da7bc68aa1ef4e9303
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/330944
Commit-Queue: Brian Quinlan <[email protected]>
Reviewed-by: Lasse Nielsen <[email protected]>

sdk/lib/io/file.dart

@@ -520,6 +520,11 @@ abstract interface class File implements FileSystemEntity {
   /// file if it already exists. In order to append the bytes to an existing
   /// file, pass [FileMode.append] as the optional mode parameter.
   ///
+  /// The elements of [bytes] should be integers in the range 0 to 255.
+  /// Any integer, which is not in that range, is converted to a byte before
+  /// being written. The conversion is equivalent to doing
+  /// `value.toUnsigned(8)`.
+  ///
   /// If the argument [flush] is set to `true`, the data written will be
   /// flushed to the file system before the returned future completes.
   Future<File> writeAsBytes(List<int> bytes,
@@ -533,6 +538,11 @@ abstract interface class File implements FileSystemEntity {
   /// the file if it already exists. In order to append the bytes to an existing
   /// file, pass [FileMode.append] as the optional mode parameter.
   ///
+  /// The elements of [bytes] should be integers in the range 0 to 255.
+  /// Any integer, which is not in that range, is converted to a byte before
+  /// being written. The conversion is equivalent to doing
+  /// `value.toUnsigned(8)`.
+  ///
   /// If the [flush] argument is set to `true` data written will be
   /// flushed to the file system before returning.
   ///