encoding/json: document coercion of invalid UTF-8 characters

Fixes #8342.

LGTM=iant
R=golang-codereviews, iant
CC=golang-codereviews
https://golang.org/cl/122180043

diff --git a/src/pkg/encoding/json/encode.go b/src/pkg/encoding/json/encode.go
index 741ddd89cbe7ca617e334669b4d776963c6006f3..5341a3a01b753d66a9f306700ac9e88f614bf664 100644 (file)
--- a/src/pkg/encoding/json/encode.go
+++ b/src/pkg/encoding/json/encode.go
@@ -40,8 +40,8 @@ import (
 //
 // Floating point, integer, and Number values encode as JSON numbers.
 //
-// String values encode as JSON strings. InvalidUTF8Error will be returned
-// if an invalid UTF-8 sequence is encountered.
+// String values encode as JSON strings coerced to valid UTF-8,
+// replacing invalid bytes with the Unicode replacement rune.
 // The angle brackets "<" and ">" are escaped to "\u003c" and "\u003e"
 // to keep some browsers from misinterpreting JSON output as HTML.
 // Ampersand "&" is also escaped to "\u0026" for the same reason.