Mention that IOSink truncates List<int> to bytes

Closes #31670

In `add` and `addStream` mention that int values which are too large are
truncated to bytes.

R=lrn@google.com

Change-Id: Idf276fc65592e21766659e9d89dd687c441b7357
CoreLibraryReviewExempt: Doc changes only.
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/310768
Auto-Submit: Nate Bosch <nbosch@google.com>
Reviewed-by: Lasse Nielsen <lrn@google.com>
Commit-Queue: Nate Bosch <nbosch@google.com>

sdk/lib/io/io_sink.dart

@@ -9,6 +9,14 @@ part of dart.io;
 /// An [IOSink] combines a [StreamSink] of bytes with a [StringSink],
 /// and allows easy output of both bytes and text.
 ///
+/// An `IOSink` is intended for writing bytes.
+/// Strings written through [write] or [writeCharCode] will be converted
+/// to bytes using [encoding].
+/// Integer data added using [add] or [addStream] will be treated as byte data,
+/// and will be truncated to unsigned 8-bit values as by using [int.toUnsigned].
+/// No guarantees are given for when such a conversion happens, since it
+/// depends on the implementation behind the sink.
+///
 /// Writing text ([write]) and adding bytes ([add]) may be interleaved freely.
 ///
 /// While a stream is being added using [addStream], any further attempts
@@ -43,6 +51,10 @@ abstract interface class IOSink implements StreamSink<List<int>>, StringSink {
   /// The data list should not be modified after it has been passed to `add`
   /// because it is not defined whether the target consumer will receive the
   /// list in the original or modified state.
+  ///
+  /// Individual values in [data] which are not in the range 0 .. 255 will be
+  /// truncated to their low eight bits, as if by [int.toUnsigned], before being
+  /// used.
   void add(List<int> data);
 
   /// Converts [object] to a String by invoking [Object.toString] and
@@ -95,6 +107,10 @@ abstract interface class IOSink implements StreamSink<List<int>>, StringSink {
   ///
   /// This method must not be called when a stream is currently being added
   /// using this method.
+  ///
+  /// Individual values in the lists emitted by [stream] which are not in the
+  /// range 0 .. 255 will be truncated to their low eight bits, as if by
+  /// [int.toUnsigned], before being used.
   Future addStream(Stream<List<int>> stream);
 
   /// Returns a [Future] that completes once all buffered data is accepted by the