encoding/json/jsontext: add symbolic Kind constants

Add constants for each possible Kind value (KindNull, KindTrue, etc.).
Leave the values unchanged ('n', 't', etc.).
Update documentation to reference the symbols.

Fixes #71756

Change-Id: Ib33b2ad9ee55f6f547d9e6a1c5a7f00c8400d3d3
Reviewed-on: https://go-review.googlesource.com/c/go/+/728420
Auto-Submit: Damien Neil <dneil@google.com>
Reviewed-by: Joseph Tsai <joetsai@digital-static.net>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

4 files changed, 26 insertions, 22 deletions

diff --git a/src/encoding/json/jsontext/decode.go b/src/encoding/json/jsontext/decode.go
index 511832f2ae..48d66fb1d4 100644
--- a/src/encoding/json/jsontext/decode.go
+++ b/src/encoding/json/jsontext/decode.go
@@ -306,7 +306,7 @@ func (d *decodeBuffer) PreviousTokenOrValue() []byte {
 
 // PeekKind retrieves the next token kind, but does not advance the read offset.
 //
-// It returns 0 if an error occurs. Any such error is cached until
+// It returns [KindInvalid] if an error occurs. Any such error is cached until
 // the next read call and it is the caller's responsibility to eventually
 // follow up a PeekKind call with a read call.
 func (d *Decoder) PeekKind() Kind {
@@ -1154,9 +1154,9 @@ func (d *Decoder) StackDepth() int {
 // It must be a number between 0 and [Decoder.StackDepth], inclusive.
 // For each level, it reports the kind:
 //
-//   - 0 for a level of zero,
-//   - '{' for a level representing a JSON object, and
-//   - '[' for a level representing a JSON array.
+//   - [KindInvalid] for a level of zero,
+//   - [KindBeginObject] for a level representing a JSON object, and
+//   - [KindBeginArray] for a level representing a JSON array.
 //
 // It also reports the length of that JSON object or array.
 // Each name and value in a JSON object is counted separately,
diff --git a/src/encoding/json/jsontext/encode.go b/src/encoding/json/jsontext/encode.go
index e3b9c04ca6..20f020700b 100644
--- a/src/encoding/json/jsontext/encode.go
+++ b/src/encoding/json/jsontext/encode.go
@@ -946,9 +946,9 @@ func (e *Encoder) StackDepth() int {
 // It must be a number between 0 and [Encoder.StackDepth], inclusive.
 // For each level, it reports the kind:
 //
-//   - 0 for a level of zero,
-//   - '{' for a level representing a JSON object, and
-//   - '[' for a level representing a JSON array.
+//   - [KindInvalid] for a level of zero,
+//   - [KindBeginObject] for a level representing a JSON object, and
+//   - [KindBeginArray] for a level representing a JSON array.
 //
 // It also reports the length of that JSON object or array.
 // Each name and value in a JSON object is counted separately,
diff --git a/src/encoding/json/jsontext/token.go b/src/encoding/json/jsontext/token.go
index caf0174923..6d9ad4b499 100644
--- a/src/encoding/json/jsontext/token.go
+++ b/src/encoding/json/jsontext/token.go
@@ -472,29 +472,33 @@ func (t Token) Kind() Kind {
 	}
 }
 
+// A Kind represents the kind of a JSON token.
+//
 // Kind represents each possible JSON token kind with a single byte,
 // which is conveniently the first byte of that kind's grammar
-// with the restriction that numbers always be represented with '0':
-//
-//   - 'n': null
-//   - 'f': false
-//   - 't': true
-//   - '"': string
-//   - '0': number
-//   - '{': object begin
-//   - '}': object end
-//   - '[': array begin
-//   - ']': array end
-//
-// An invalid kind is usually represented using 0,
-// but may be non-zero due to invalid JSON data.
+// with the restriction that numbers always be represented with '0'.
 type Kind byte
 
+const (
+	KindInvalid     Kind = 0   // invalid kind
+	KindNull        Kind = 'n' // null
+	KindFalse       Kind = 'f' // false
+	KindTrue        Kind = 't' // true
+	KindString      Kind = '"' // string
+	KindNumber      Kind = '0' // number
+	KindBeginObject Kind = '{' // begin object
+	KindEndObject   Kind = '}' // end object
+	KindBeginArray  Kind = '[' // begin array
+	KindEndArray    Kind = ']' // end array
+)
+
 const invalidKind Kind = 0
 
 // String prints the kind in a humanly readable fashion.
 func (k Kind) String() string {
 	switch k {
+	case 0:
+		return "invalid"
 	case 'n':
 		return "null"
 	case 'f':
diff --git a/src/encoding/json/jsontext/value.go b/src/encoding/json/jsontext/value.go
index a4b06b2a94..84c919b9dc 100644
--- a/src/encoding/json/jsontext/value.go
+++ b/src/encoding/json/jsontext/value.go
@@ -236,7 +236,7 @@ func (v *Value) UnmarshalJSON(b []byte) error {
 }
 
 // Kind returns the starting token kind.
-// For a valid value, this will never include '}' or ']'.
+// For a valid value, this will never include [KindEndObject] or [KindEndArray].
 func (v Value) Kind() Kind {
 	if v := v[jsonwire.ConsumeWhitespace(v):]; len(v) > 0 {
 		return Kind(v[0]).normalize()