Adjust documentation to match new UTF-8 encoder/decoder behavior (#43)
diff --git a/lib/src/utf8.dart b/lib/src/utf8.dart
index df8f1f2..d5787f0 100644
--- a/lib/src/utf8.dart
+++ b/lib/src/utf8.dart
@@ -32,10 +32,8 @@
/// Creates a [String] containing the characters UTF-8 encoded in [string].
///
/// The [string] must be a zero-terminated byte sequence of valid UTF-8
- /// encodings of Unicode code points. It may also contain UTF-8 encodings of
- /// unpaired surrogate code points, which is not otherwise valid UTF-8, but
- /// which may be created when encoding a Dart string containing an unpaired
- /// surrogate. See [Utf8Decoder] for details on decoding.
+ /// encodings of Unicode scalar values. A [FormatException] is thrown if the
+ /// input is malformed. See [Utf8Decoder] for details on decoding.
///
/// Returns a Dart string containing the decoded code points.
static String fromUtf8(Pointer<Utf8> string) {
@@ -47,7 +45,8 @@
/// Convert a [String] to a Utf8-encoded null-terminated C string.
///
/// If 'string' contains NULL bytes, the converted string will be truncated
- /// prematurely. Unpaired surrogate code points in [string] will be preserved
+ /// prematurely. Unpaired surrogate code points in [string] will be encoded
+ /// as replacement characters (U+FFFD, encoded as the bytes 0xEF 0xBF 0xBD)
/// in the UTF-8 encoded result. See [Utf8Encoder] for details on encoding.
///
/// Returns a malloc-allocated pointer to the result.
