encoding/json/jsontext: expand Decoder.UnreadBuffer documentation

Expand the documentation on Decoder.UnreadBuffer regarding
what exactly it returns, what guarantees are provided, and
how to properly use it for the most common use-case of
obtaining everything else after the last parsed token.

Also update documentation in v1 json.Decoder.Buffered method,
which is trivially implemented under the hood
using Decoder.UnreadBuffer.

Updates #79498

Change-Id: I9c4a9350e97b74d77d4a74dd191fba6097ae332a
Reviewed-on: https://go-review.googlesource.com/c/go/+/779981
Reviewed-by: Damien Neil <dneil@google.com>
LUCI-TryBot-Result: golang-scoped@luci-project-accounts.iam.gserviceaccount.com <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Michael Pratt <mpratt@google.com>
Auto-Submit: Damien Neil <dneil@google.com>

src/encoding/json/jsontext/decode.go

@@ -1134,6 +1134,17 @@ func (d *Decoder) InputOffset() int64 {
 
 // UnreadBuffer returns the data remaining in the unread buffer,
 // which may contain zero or more bytes.
+// This is the data already consumed from the input [io.Reader],
+// but not yet read by a [Decoder.ReadToken] or [Decoder.ReadValue] call.
+// It may contain bytes that do not form valid JSON as it has not yet
+// been validated according to the JSON grammar.
+// The exact amount of buffered data is an implementation detail
+// of the Decoder and may change over time.
+//
+// It is the caller's responsibility to concatenate this buffer with
+// the remainder of the input Reader to obtain the full sequence
+// of bytes after the last read JSON token or value.
+//
 // The returned buffer must not be mutated while Decoder continues to be used.
 // The buffer contents are valid until the next Peek, Read, or Skip call.
 func (d *Decoder) UnreadBuffer() []byte {

src/encoding/json/stream.go

@@ -80,8 +80,20 @@ func (dec *Decoder) Decode(v any) error {
 	return err
 }
 
-// Buffered returns a reader of the data remaining in the Decoder's
-// buffer. The reader is valid until the next call to [Decoder.Decode].
+// Buffered returns a reader of the data remaining in the unread buffer,
+// which may contain zero or more bytes.
+// This is the data already consumed from the input [io.Reader],
+// but not yet read by a [Decoder.Decode] or [Decoder.Token] call.
+// It may contain bytes that do not form valid JSON as it has not yet
+// been validated according to the JSON grammar.
+// The exact amount of buffered data is an implementation detail
+// of the Decoder and may change over time.
+//
+// It is the caller's responsibility to concatenate this buffer with
+// the remainder of the input Reader to obtain the full sequence
+// of bytes after the last decoded JSON value.
+//
+// The reader is valid until the next call to [Decoder.Decode] or [Decoder.Token].
 func (dec *Decoder) Buffered() io.Reader {
 	return bytes.NewReader(dec.buf[dec.scanp:])
 }

src/encoding/json/v2_stream.go

@@ -85,8 +85,20 @@ func (dec *Decoder) Decode(v any) error {
 	return jsonv2.Unmarshal(b, v, dec.opts)
 }
 
-// Buffered returns a reader of the data remaining in the Decoder's
-// buffer. The reader is valid until the next call to [Decoder.Decode].
+// Buffered returns a reader of the data remaining in the unread buffer,
+// which may contain zero or more bytes.
+// This is the data already consumed from the input [io.Reader],
+// but not yet read by a [Decoder.Decode] or [Decoder.Token] call.
+// It may contain bytes that do not form valid JSON as it has not yet
+// been validated according to the JSON grammar.
+// The exact amount of buffered data is an implementation detail
+// of the Decoder and may change over time.
+//
+// It is the caller's responsibility to concatenate this buffer with
+// the remainder of the input Reader to obtain the full sequence
+// of bytes after the last decoded JSON value.
+//
+// The reader is valid until the next call to [Decoder.Decode] or [Decoder.Token].
 func (dec *Decoder) Buffered() io.Reader {
 	return bytes.NewReader(dec.dec.UnreadBuffer())
 }