From cf062e09037c7e54a821b05ef50b3e86683090f8 Mon Sep 17 00:00:00 2001
From: Luke Shumaker <lukeshu@lukeshu.com>
Date: Thu, 26 Jan 2023 13:59:35 -0700
Subject: Improve/fix documentation and comments

---
 decode.go | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

(limited to 'decode.go')

diff --git a/decode.go b/decode.go
index f911ac3..5a03d5d 100644
--- a/decode.go
+++ b/decode.go
@@ -30,22 +30,29 @@ import (
 // JSON representation of themselves.  Decodable is a
 // low-memory-overhead replacement for the json.Unmarshaler interface.
 //
-// The io.RuneScanner passed to DecodeJSON...
+// On the io.RuneScanner passed to DecodeJSON:
 //
-//   - ...will return ErrInvalidUnreadRune .UnreadRune if the last
+//   - .UnreadRune() will return ErrInvalidUnreadRune if the last
 //     operation was not a successful .ReadRune() call.
 //
-//   - ...will return EOF at the end of the JSON value; it is not
-//     possible for DecodeJSON to read past the end of the value in to
-//     another value.
+//   - .ReadRune() will return io.EOF at the end of the JSON value; it
+//     is not possible for .ReadRune() to read past the end of the
+//     value in to another value.
 //
-//   - ...if invalid JSON is encountered, will return the invalid rune
-//     with err!=nil.  Implementations are encouraged to simply
-//     `return err` if .ReadRune returns an error.
+//   - .ReadRune() will never return invalid JSON; if invalid JSON is
+//     encountered, it will use a panic-based mechanism to transfer
+//     control back to the Decoder.
+//
+//   - .ReadRune() never return an error other than io.EOF; if an I/O
+//     error is encountered, it will use a panic-based mechanism to
+//     transfer control back to the Decoder.
 //
 // DecodeJSON is expected to consume the entire scanner until io.EOF
 // or another is encountered; if it does not, then the parent Decode
 // call will return a *DecodeTypeError.
+//
+// Implementor's note: "limitingScanner" is the thing to search for in
+// decode.go if you want to read up on that io.RuneScanner.
 type Decodable interface {
 	DecodeJSON(io.RuneScanner) error
 }
-- 
cgit v1.2.3-2-g168b