better documentation

decode.go

@@ -11,6 +11,9 @@ func Unmarshal(b []byte) (any, error) {
 	return val, p.CheckEmpty()
 }
 
+// UnmarshalObject decodes JSON as a simply-typed JSON object and returns it. If
+// the JSON is a value of a type other than object, such as JSON null or a JSON
+// string, an error will be returned.
 func UnmarshalObject(b []byte) (map[string]any, error) {
 	p := NewParserFromSlice(b)
 	val, err := p.ParseObject()
@@ -31,6 +34,9 @@ func UnmarshalString(s string) (any, error) {
 	return val, p.CheckEmpty()
 }
 
+// UnmarshalObjectString decodes JSON as a simply-typed JSON object and returns
+// it. If the JSON is a value of a type other than object, such as JSON null or
+// a JSON string, an error will be returned.
 func UnmarshalObjectString(s string) (map[string]any, error) {
 	p := NewParserFromString(s)
 	val, err := p.ParseObject()

emit.go

@@ -27,8 +27,18 @@ var (
 	hexChars = [...]byte{'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'}
 )
 
+// Reusable object that can encode simple JSON values to any Writer.
 type Emitter interface {
+	// Writes the given value to the wrapped Writer. If the value or part of the
+	// value is not a supported type, an error will be returned with JSON only
+	// partially written.
+	//
+	// Supported types include: nil, bool, integers, floats, string, []byte
+	// (as a base64 encoded string), time.Time (written as an RFC3339 string),
+	// error (written as a string), and pointers/slices/string-keyed maps of
+	// supported types.
 	Emit(val any) error
+	// Replaces the Writer that this Emitter writes to.
 	Reset(io.Writer)
 }
 
@@ -38,6 +48,7 @@ type emitter struct {
 	a [128]byte
 }
 
+// Creates a new Emitter wrapping the given Writer.
 func NewEmitter(w io.Writer) Emitter {
 	e := &emitter{w: w}
 	e.s = e.a[:0]

encode.go

@@ -5,7 +5,13 @@ import (
 	"strings"
 )
 
-// Marshal writes the JSON representation of v to a byte slice returned in b.
+// Marshal writes the JSON representation of the given value to a byte slice.
+//
+// The given value is expected to contain only supported types, which include:
+// nil, bool, integers, floats, string, []byte (as a base64 encoded string),
+// time.Time (written as an RFC3339 string), error (written as a string), and
+// pointers/slices/string-keyed maps of supported types. If a type in v is not
+// supported, an error will be returned.
 func Marshal(v interface{}) (b []byte, err error) {
 	var buf bytes.Buffer
 	err = NewEmitter(&buf).Emit(v)
@@ -15,6 +21,14 @@ func Marshal(v interface{}) (b []byte, err error) {
 	return buf.Bytes(), nil
 }
 
+// MarshalToString writes the JSON representation of the given value to a
+// string.
+//
+// The given value is expected to contain only supported types, which include:
+// nil, bool, integers, floats, string, []byte (as a base64 encoded string),
+// time.Time (written as an RFC3339 string), error (written as a string), and
+// pointers/slices/string-keyed maps of supported types. If a type in v is not
+// supported, an error will be returned.
 func MarshalToString(v interface{}) (s string, err error) {
 	var sb strings.Builder
 	err = NewEmitter(&sb).Emit(v)

parse.go

@@ -53,7 +53,7 @@ type Parser interface {
 	// returned.
 	Parse() (any, error)
 	// ParseObject parses JSON from the front of the contained data as a
-	// simply-typed JSON object and return it. If the JSON is a value of a type
+	// simply-typed JSON object and returns it. If the JSON is a value of a type
 	// other than object, an error will be returned. If the data is empty, the
 	// exact error io.EOF will be returned.
 	ParseObject() (map[string]any, error)