Improve/fix documentation and comments

1 files changed, 15 insertions, 8 deletions

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
 }