Documentation update for Utf8Encoder and Utf8Decoder

Examples for Utf8Encoder and Utf8Decoder usage.
Some small text updates done.

Closes #47622
#47622

GitOrigin-RevId: 8fa3688
Change-Id: I5fa545128bdbec7b27a1bc35c01d5764ddd2a432
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/219281
Reviewed-by: Lasse R.H. Nielsen <[email protected]>
Commit-Queue: Lasse R.H. Nielsen <[email protected]>

Author: jpsiitonen

sdk/lib/convert/utf.dart

@@ -40,7 +40,7 @@ class Utf8Codec extends Encoding {
   const Utf8Codec({bool allowMalformed = false})
       : _allowMalformed = allowMalformed;
 
-  /// The name of this codec, "utf-8".
+  /// The name of this codec is "utf-8".
   String get name => "utf-8";
 
   /// Decodes the UTF-8 [codeUnits] (a list of unsigned 8-bit integers) to the
@@ -49,7 +49,7 @@ class Utf8Codec extends Encoding {
   /// If the [codeUnits] start with the encoding of a
   /// [unicodeBomCharacterRune], that character is discarded.
   ///
-  /// If [allowMalformed] is `true` the decoder replaces invalid (or
+  /// If [allowMalformed] is `true`, the decoder replaces invalid (or
   /// unterminated) character sequences with the Unicode Replacement character
   /// `U+FFFD` (�). Otherwise it throws a [FormatException].
   ///
@@ -74,6 +74,14 @@ class Utf8Codec extends Encoding {
 
 /// This class converts strings to their UTF-8 code units (a list of
 /// unsigned 8-bit integers).
+///
+/// Example:
+/// ```dart
+/// final utf8Encoder = utf8.encoder;
+/// const sample = 'Îñţérñåţîöñåļîžåţîờñ';
+/// final encodedSample = utf8Encoder.convert(sample);
+/// print(encodedSample);
+/// ```
 class Utf8Encoder extends Converter<String, List<int>> {
   const Utf8Encoder();
 
@@ -148,10 +156,10 @@ class _Utf8Encoder {
   /// writes it to [_buffer].
   ///
   /// Returns true if the [nextCodeUnit] was combined with the
-  /// [leadingSurrogate]. If it wasn't then nextCodeUnit was not a trailing
+  /// [leadingSurrogate]. If it wasn't, then nextCodeUnit was not a trailing
   /// surrogate and has not been written yet.
   ///
-  /// It is safe to pass 0 for [nextCodeUnit] in which case a replacement
+  /// It is safe to pass 0 for [nextCodeUnit], in which case a replacement
   /// character is written to represent the unpaired lead surrogate.
   bool _writeSurrogate(int leadingSurrogate, int nextCodeUnit) {
     if (_isTailSurrogate(nextCodeUnit)) {
@@ -285,6 +293,31 @@ class _Utf8EncoderSink extends _Utf8Encoder with StringConversionSinkMixin {
 
 /// This class converts UTF-8 code units (lists of unsigned 8-bit integers)
 /// to a string.
+///
+/// Example:
+/// ```dart
+/// final utf8Decoder = utf8.decoder;
+/// const encodedBytes = [
+///   195, 142, 195, 177, 197, 163, 195, 169, 114, 195, 177, 195, 165, 197,
+///   163, 195, 174, 195, 182, 195, 177, 195, 165, 196, 188, 195, 174, 197,
+///   190, 195, 165, 197, 163, 195, 174, 225, 187, 157, 195, 177];
+///
+/// final decodedBytes = utf8Decoder.convert(encodedBytes);
+/// print(decodedBytes); // Îñţérñåţîöñåļîžåţîờñ
+/// ```
+/// Throws a [FormatException] if the encoded input contains
+/// invalid UTF-8 byte sequences and [allowMalformed] is `false` (the default).
+///
+/// If [allowMalformed] is `true`, invalid byte sequences are converted into
+/// one or more Unicode replacement characters, U+FFFD ('�').
+///
+/// Example with `allowMalformed` set to true:
+/// ```dart
+/// const utf8Decoder = Utf8Decoder(allowMalformed: true);
+/// const encodedBytes = [0xFF];
+/// final decodedBytes = utf8Decoder.convert(encodedBytes);
+/// print(decodedBytes); // �
+/// ```
 class Utf8Decoder extends Converter<List<int>, String> {
   final bool _allowMalformed;
 
@@ -293,7 +326,7 @@ class Utf8Decoder extends Converter<List<int>, String> {
   /// The optional [allowMalformed] argument defines how [convert] deals
   /// with invalid or unterminated character sequences.
   ///
-  /// If it is `true` [convert] replaces invalid (or unterminated) character
+  /// If it is `true`, [convert] replaces invalid (or unterminated) character
   /// sequences with the Unicode Replacement character `U+FFFD` (�). Otherwise
   /// it throws a [FormatException].
   const Utf8Decoder({bool allowMalformed = false})
@@ -302,7 +335,7 @@ class Utf8Decoder extends Converter<List<int>, String> {
   /// Converts the UTF-8 [codeUnits] (a list of unsigned 8-bit integers) to the
   /// corresponding string.
   ///
-  /// Uses the code units from [start] to, but no including, [end].
+  /// Uses the code units from [start] to, but not including, [end].
   /// If [end] is omitted, it defaults to `codeUnits.length`.
   ///
   /// If the [codeUnits] start with the encoding of a