encoding/json: document HTML escaping in Compact

Make explicit that Compact does HTML escaping.

Fixes #30357.

Change-Id: I4648f8f3e907d659db977d07253f716df6e07d7b
Reviewed-on: https://go-review.googlesource.com/c/go/+/173417
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

2 files changed, 9 insertions, 5 deletions

diff --git a/src/encoding/json/encode.go b/src/encoding/json/encode.go
index 197c0cba03..383460e52b 100644
--- a/src/encoding/json/encode.go
+++ b/src/encoding/json/encode.go
@@ -45,11 +45,12 @@ import (
 //
 // 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.
-// This escaping can be disabled using an Encoder that had SetEscapeHTML(false)
-// called on it.
+// So that the JSON will be safe to embed inside HTML <script> tags,
+// the string is encoded using HTMLEscape,
+// which replaces "<", ">", "&", U+2028, and U+2029 are escaped
+// to "\u003c","\u003e", "\u0026", "\u2028", and "\u2029".
+// This replacement can be disabled when using an Encoder,
+// by calling SetEscapeHTML(false).
 //
 // Array and slice values encode as JSON arrays, except that
 // []byte encodes as a base64-encoded string, and a nil slice
diff --git a/src/encoding/json/indent.go b/src/encoding/json/indent.go
index fba19548c9..1b49a369e3 100644
--- a/src/encoding/json/indent.go
+++ b/src/encoding/json/indent.go
@@ -8,6 +8,9 @@ import "bytes"
 
 // Compact appends to dst the JSON-encoded src with
 // insignificant space characters elided.
+// Like Marshal, Compact applies HTMLEscape to any
+// string literals so that the JSON will be safe to embed
+// inside HTML <script> tags.
 func Compact(dst *bytes.Buffer, src []byte) error {
 	return compact(dst, src, false)
 }