Adjust and cleanup documentation (#319)

jsontext/decode.go

@@ -574,7 +574,10 @@ func (d *decoderState) ReadToken() (Token, error) {
 }
 
 // ReadValue returns the next raw JSON value, advancing the read offset.
-// The value is stripped of any leading or trailing whitespace.
+// The value is stripped of any leading or trailing whitespace and
+// contains the exact bytes of the input, which may contain invalid UTF-8
+// if [AllowInvalidUTF8] is specified.
+//
 // The returned value is only valid until the next Peek, Read, or Skip call and
 // may not be mutated while the Decoder remains in use.
 // If the decoder is currently at the end token for an object or array,

jsontext/doc.go

@@ -9,7 +9,9 @@
 // in addition to structured data types such as objects and arrays.
 //
 // The [Encoder] and [Decoder] types are used to encode or decode
-// a stream of JSON values or tokens.
+// a stream of JSON tokens or values.
+//
+// # Tokens and Values
 //
 // A JSON token refers to the basic structural elements of JSON:
 //
@@ -21,7 +23,7 @@
 //
 // A JSON token is represented by the [Token] type in Go. Technically,
 // there are two additional structural characters (i.e., ':' and ','),
-// but there is no Token representation for them since their presence
+// but there is no [Token] representation for them since their presence
 // can be inferred by the structure of the JSON grammar itself.
 // For example, there must always be an implicit colon between
 // the name and value of a JSON object member.
@@ -45,11 +47,13 @@
 //
 // # Terminology
 //
-// This package uses the terms "encode" and "decode" for syntactic functionality
+// The terms "encode" and "decode" are used for syntactic functionality
 // that is concerned with processing JSON based on its grammar, and
-// uses the terms "marshal" and "unmarshal" for semantic functionality
+// the terms "marshal" and "unmarshal" are used for semantic functionality
 // that determines the meaning of JSON values as Go values and vice-versa.
-// It aims to provide a clear distinction between functionality that
+// This package (i.e., [jsontext]) deals with JSON at a syntactic layer,
+// while [encoding/json/v2] deals with JSON at a semantic layer.
+// The goal is to provide a clear distinction between functionality that
 // is purely concerned with encoding versus that of marshaling.
 // For example, one can directly encode a stream of JSON tokens without
 // needing to marshal a concrete Go value representing them.

jsontext/encode.go

@@ -494,6 +494,8 @@ func (e *encoderState) AppendRaw(k Kind, safeASCII bool, appendFn func([]byte) (
 // The Encoder does not simply copy the provided value verbatim, but
 // parses it to ensure that it is syntactically valid and reformats it
 // according to how the Encoder is configured to format whitespace and strings.
+// If [AllowInvalidUTF8] is specified, then any invalid UTF-8 is mangled
+// as the Unicode replacement character, U+FFFD.
 //
 // The provided value kind must be consistent with the JSON grammar
 // (see examples on [Encoder.WriteToken]). If the provided value is invalid,

jsontext/options.go

@@ -53,7 +53,7 @@ func AllowInvalidUTF8(v bool) Options {
 }
 
 // EscapeForHTML specifies that '<', '>', and '&' characters within JSON strings
-// should be escaped as a hexadecimal Unicode codepoint (e.g., \ufffd) so that
+// should be escaped as a hexadecimal Unicode codepoint (e.g., \u003c) so that
 // the output is safe to embed within HTML.
 //
 // This only affects encoding and is ignored when decoding.
@@ -66,7 +66,7 @@ func EscapeForHTML(v bool) Options {
 }
 
 // EscapeForJS specifies that U+2028 and U+2029 characters within JSON strings
-// should be escaped as a hexadecimal Unicode codepoint (e.g., \ufffd) so that
+// should be escaped as a hexadecimal Unicode codepoint (e.g., \u2028) so that
 // the output is valid to embed within JavaScript. See RFC 8259, section 12.
 //
 // This only affects encoding and is ignored when decoding.

v1/options.go

@@ -25,6 +25,8 @@ var (
 
 // Options are a set of options to configure the v2 "json" package
 // to operate with v1 semantics for particular features.
+// Values of this type can be passed to v2 functions like
+// [jsonv2.Marshal] or [jsonv2.Unmarshal].
 // Instead of referencing this type, use ["encoding/json/v2".Options].
 type Options = jsonopts.Options
 
@@ -48,6 +50,12 @@ type Options = jsonopts.Options
 // All other boolean options are set to false.
 // All non-boolean options are set to the zero value,
 // except for [jsontext.WithIndent], which defaults to "\t".
+//
+// The [Marshal] and [Unmarshal] functions in this package are
+// semantically identical to calling the v2 equivalents with this option:
+//
+//	jsonv2.Marshal(v, jsonv1.DefaultOptionsV1())
+//	jsonv2.Unmarshal(b, v, jsonv1.DefaultOptionsV1())
 func DefaultOptionsV1() Options {
 	return &jsonopts.DefaultOptionsV1
 }