Documentation update for StringBuffer

Added example code to StringBuffer.

Closes dart-lang/sdk#47809
dart-lang/sdk#47809

GitOrigin-RevId: d12b7bb1bc4c309f0191698ee58b44ab7d0b8006
Change-Id: I59343029742bb60e8ea5151a345eed3a20268624
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/221600
Reviewed-by: Lasse Nielsen <lrn@google.com>
Commit-Queue: Lasse Nielsen <lrn@google.com>

Author: jpsiitonen

sdk/lib/core/string_buffer.dart

@@ -9,8 +9,71 @@ part of dart.core;
 /// Allows for the incremental building of a string using `write*()` methods.
 /// The strings are concatenated to a single string only when [toString] is
 /// called.
+///
+/// Example:
+/// ```dart
+/// final buffer = StringBuffer('DART');
+/// print(buffer.length); // 4
+/// ```
+/// To add the string representation of an object, as returned by
+/// [Object.toString], to the buffer, use [write].
+/// Is also used for adding a string directly.
+/// ```
+/// buffer.write(' is open source');
+/// print(buffer.length); // 19
+/// print(buffer); // DART is open source
+///
+/// const int dartYear = 2011;
+/// buffer
+///   ..write(' since ') // Writes a string.
+///   ..write(dartYear); // Writes an int.
+/// print(buffer); // DART is open source since 2011
+/// print(buffer.length); // 30
+/// ```
+/// To add a newline after the object's string representation, use [writeln].
+/// Calling [writeln] with no argument adds a single newline to the buffer.
+/// ```
+/// buffer.writeln(); // Contains "DART is open source since 2011\n".
+/// buffer.writeln('-' * (buffer.length - 1)); // 30 '-'s and a newline.
+/// print(buffer.length); // 62
+/// ```
+/// To write multiple objects to the buffer, use [writeAll].
+/// ```
+/// const separator = '-';
+/// buffer.writeAll(['Dart', 'is', 'fun!'], separator);
+/// print(buffer.length); // 74
+/// print(buffer);
+/// // DART is open source since 2011
+/// // ------------------------------
+/// // Dart-is-fun!
+/// ```
+/// To add the string representation of a Unicode code point, `charCode`,
+/// to the buffer, use [writeCharCode].
+/// ```
+/// buffer.writeCharCode(0x0A); // LF (line feed)
+/// buffer.writeCharCode(0x44); // 'D'
+/// buffer.writeCharCode(0x61); // 'a'
+/// buffer.writeCharCode(0x72); // 'r'
+/// buffer.writeCharCode(0x74); // 't'
+/// print(buffer.length); // 79
+/// ```
+/// To convert the content to a single string, use [toString].
+/// ```
+/// final text = buffer.toString();
+/// print(text);
+/// // DART is open source since 2011
+/// // ------------------------------
+/// // Dart-is-fun!
+/// // Dart
+/// ```
+/// To clear the buffer, so that it can be reused, use [clear].
+/// ```
+/// buffer.clear();
+/// print(buffer.isEmpty); // true
+/// print(buffer.length); // 0
+/// ```
 class StringBuffer implements StringSink {
-  /// Creates the string buffer with an initial content.
+  /// Creates a string buffer containing the provided [content].
   external StringBuffer([Object content = ""]);
 
   /// Returns the length of the content that has been accumulated so far.