Fix doc comments (#151)

Author: dsnet

arshal.go

@@ -124,7 +124,7 @@ func putStructOptions(o *jsonopts.Struct) {
 //     is recursively encoded as a name and value pair in the JSON object.
 //     The Go map key must encode as a JSON string, otherwise this results
 //     in a [SemanticError]. The Go map is traversed in a non-deterministic order.
-//     For deterministic encoding, consider using [jsontext.Value.Canonicalize].
+//     For deterministic encoding, consider using the [Deterministic] option.
 //     If the format is "emitnull", then a nil map is encoded as a JSON null.
 //     If the format is "emitempty", then a nil map is encoded as an empty JSON object,
 //     regardless of whether [FormatNilMapAsNull] is specified.
@@ -335,7 +335,7 @@ func marshalEncode(out *jsontext.Encoder, in any, mo *jsonopts.Struct) (err erro
 //   - A Go float is decoded from a JSON number.
 //     It must be decoded from a JSON string containing a JSON number
 //     if [StringifyNumbers] is specified or decoding a JSON object name.
-//     The JSON number is parsed as the closest representable Go float value.
+//     It fails if it overflows the representation of the Go float type.
 //     If the format is "nonfinite", then the JSON strings
 //     "NaN", "Infinity", and "-Infinity" are decoded as NaN, +Inf, and -Inf.
 //     Otherwise, the presence of such strings results in a [SemanticError].

jsontext/decode.go

@@ -285,7 +285,10 @@ func (d *decodeBuffer) PreviousTokenOrValue() []byte {
 }
 
 // PeekKind retrieves the next token kind, but does not advance the read offset.
-// It returns 0 if there are no more tokens.
+//
+// It returns 0 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 {
 	return d.s.PeekKind()
 }

jsontext/options.go

@@ -17,6 +17,25 @@ import (
 // Each function takes in a variadic list of options, where properties
 // set in latter options override the value of previously set properties.
 //
+// There is a single Options type, which is used with both encoding and decoding.
+// Some options affect both operations, while others only affect one operation:
+//
+//   - [AllowDuplicateNames] affects encoding and decoding
+//   - [AllowInvalidUTF8] affects encoding and decoding
+//   - [EscapeForHTML] affects encoding only
+//   - [EscapeForJS] affects encoding only
+//   - [PreserveRawStrings] affects encoding only
+//   - [CanonicalizeRawInts] affects encoding only
+//   - [CanonicalizeRawFloats] affects encoding only
+//   - [ReorderRawObjects] affects encoding only
+//   - [SpaceAfterColon] affects encoding only
+//   - [SpaceAfterComma] affects encoding only
+//   - [Multiline] affects encoding only
+//   - [WithIndent] affects encoding only
+//   - [WithIndentPrefix] affects encoding only
+//
+// Options that do not affect a particular operation are ignored.
+//
 // The Options type is identical to [encoding/json.Options] and
 // [encoding/json/v2.Options]. Options from the other packages may
 // be passed to functionality in this package, but are ignored.

options.go

@@ -61,6 +61,7 @@ import (
 //   - [Deterministic] affects marshaling only
 //   - [FormatNilSliceAsNull] affects marshaling only
 //   - [FormatNilMapAsNull] affects marshaling only
+//   - [OmitZeroStructFields] affects marshaling only
 //   - [MatchCaseInsensitiveNames] affects marshaling and unmarshaling
 //   - [DiscardUnknownMembers] affects marshaling only
 //   - [RejectUnknownMembers] affects unmarshaling only