Write documentationv0.2.0

1 files changed, 38 insertions, 30 deletions

diff --git a/errors.go b/errors.go
index 67fe6c9..5669d36 100644
--- a/errors.go
+++ b/errors.go
@@ -1,4 +1,4 @@
-// Copyright (C) 2022  Luke Shumaker <lukeshu@lukeshu.com>
+// Copyright (C) 2022-2023  Luke Shumaker <lukeshu@lukeshu.com>
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
@@ -14,21 +14,23 @@ import (
 	"git.lukeshu.com/go/lowmemjson/internal"
 )
 
-var (
-	ErrInvalidUnreadRune = errors.New("lowmemjson: invalid use of UnreadRune")
-)
+// ErrInvalidUnreadRune is returned to Decodable.DecodeJSON(scanner)
+// implementations from scanner.UnreadRune() if the last operation was
+// not a successful .ReadRune() call.
+var ErrInvalidUnreadRune = errors.New("lowmemjson: invalid use of UnreadRune")
 
 // parser errors ///////////////////////////////////////////////////////////////////////////////////
 
-var (
-	ErrParserExceededMaxDepth = internal.ErrParserExceededMaxDepth
-)
+// ErrParserExceededMaxDepth is the base error that a
+// *DecodeSyntaxError wraps when the depth of the JSON document
+// exceeds 10000.
+var ErrParserExceededMaxDepth = internal.ErrParserExceededMaxDepth
 
 // low-level decode errors /////////////////////////////////////////////////////////////////////////
 // These will be wrapped in a *DecodeError.
 
-// A *DecodeReadError is returned from Decode if there is an I/O error
-// reading the input.
+// A *DecodeReadError is returned from Decode (wrapped in a
+// *DecodeError) if there is an I/O error reading the input.
 type DecodeReadError struct {
 	Err    error
 	Offset int64
@@ -39,8 +41,8 @@ func (e *DecodeReadError) Error() string {
 }
 func (e *DecodeReadError) Unwrap() error { return e.Err }
 
-// A *DecodeSyntaxError is returned from Decode if there is a syntax
-// error in the input.
+// A *DecodeSyntaxError is returned from Decode (wrapped in a
+// *DecodeError) if there is a syntax error in the input.
 type DecodeSyntaxError struct {
 	Err    error
 	Offset int64
@@ -51,8 +53,9 @@ func (e *DecodeSyntaxError) Error() string {
 }
 func (e *DecodeSyntaxError) Unwrap() error { return e.Err }
 
-// A *DecodeTypeError is returned from Decode if the JSON input is not
-// appropriate for the given Go type.
+// A *DecodeTypeError is returned from Decode (wrapped in a
+// *DecodeError) if the JSON input is not appropriate for the given Go
+// type.
 //
 // If a .DecodeJSON, .UnmarshalJSON, or .UnmashaleText method returns
 // an error, it is wrapped in a *DecodeTypeError.
@@ -69,7 +72,7 @@ func (e *DecodeTypeError) Error() string {
 	if e.JSONType != "" {
 		fmt.Fprintf(&buf, "JSON %s ", e.JSONType)
 	}
-	fmt.Fprintf(&buf, "at input byte %v in to Go %v", e.Offset, e.GoType)
+	fmt.Fprintf(&buf, "at input byte %v into Go %v", e.Offset, e.GoType)
 	if e.Err != nil {
 		fmt.Fprintf(&buf, ": %v", strings.TrimPrefix(e.Err.Error(), "json: "))
 	}
@@ -78,9 +81,10 @@ func (e *DecodeTypeError) Error() string {
 
 func (e *DecodeTypeError) Unwrap() error { return e.Err }
 
-var (
-	ErrDecodeNonEmptyInterface = errors.New("cannot decode in to non-empty interface")
-)
+// ErrDecodeNonEmptyInterface is the base error that a
+// *DecodeTypeError wraps when Decode is asked to unmarshal into an
+// `interface` type that has one or more methods.
+var ErrDecodeNonEmptyInterface = errors.New("cannot decode into non-empty interface")
 
 // high-level decode errors ////////////////////////////////////////////////////////////////////////
 
@@ -88,21 +92,26 @@ var (
 // not a non-nil pointer or is not settable.
 //
 // Alternatively, a *DecodeArgument error may be found inside of a
-// *DecodeTypeError if the type being decoded in to is not a type that
-// can be decoded in to (such as map with non-stringable type as
-// keys).
+// *DecodeTypeError if the type being decoded into is not a type that
+// can be decoded into (such as map with non-stringable type as keys).
 //
 //	type DecodeArgumentError struct {
 //	    Type reflect.Type
 //	}
 type DecodeArgumentError = json.InvalidUnmarshalError
 
+// A *DecodeError is returned from Decode for all errors except for
+// *DecodeArgumentError.
+//
+// A *DecodeError wraps *DecodeSyntaxError for malformed or illegal
+// input, *DecodeTypeError for Go type issues, or *DecodeReadError for
+// I/O errors.
 type DecodeError struct {
-	Field string
-	Err   error
+	Field string // Where in the JSON the error was, in the form "v[idx][idx][idx]".
+	Err   error  // What the error was.
 
-	FieldParent string // for compat
-	FieldName   string // for compat
+	FieldParent string // for compat; the same as encoding/json.UnmarshalTypeError.Struct
+	FieldName   string // for compat; the same as encoding/json.UnmarshalTypeError.Field
 }
 
 func (e *DecodeError) Error() string {
@@ -129,19 +138,18 @@ type EncodeTypeError = json.UnsupportedTypeError
 //	}
 type EncodeValueError = json.UnsupportedValueError
 
-// An *EncodeTypeError is returned by Encode when attempting to encode
-// an unsupported value type.
+// An *EncodeMethodError wraps an error that is returned from an
+// object's method when encoding that object to JSON.
 type EncodeMethodError struct {
-	Type       reflect.Type
-	Err        error
-	SourceFunc string
+	Type       reflect.Type // The Go type that the method is on
+	SourceFunc string       // The method: "EncodeJSON", "MarshalJSON", or "MarshalText"
+	Err        error        // The error that the method returned
 }
 
 func (e *EncodeMethodError) Error() string {
 	return fmt.Sprintf("json: error calling %v for type %v: %v",
 		e.SourceFunc, e.Type, strings.TrimPrefix(e.Err.Error(), "json: "))
 }
-
 func (e *EncodeMethodError) Unwrap() error { return e.Err }
 
 // reencode errors /////////////////////////////////////////////////////////////////////////////////