Improve/fix documentation and comments

1 files changed, 13 insertions, 9 deletions

diff --git a/reencode.go b/reencode.go
index b20a503..1bcfc74 100644
--- a/reencode.go
+++ b/reencode.go
@@ -30,6 +30,10 @@ type speculation struct {
 // The memory use of a ReEncoder is O( (CompactIfUnder+1)^2 + depth).
 type ReEncoder struct {
 	// The output stream to write the re-encoded JSON to.
+	//
+	// A ReEncoder tends to make many small writes; if Out.Write
+	// calls are syscalls, then you may want to wrap Out in a
+	// bufio.Writer.
 	Out io.Writer
 
 	// A JSON document is specified to be a single JSON element;
@@ -99,14 +103,14 @@ type ReEncoder struct {
 
 // public API //////////////////////////////////////////////////////////////////
 
-// Write implements io.Writer; it does what you'd expect, mostly.
+// Write implements io.Writer; it does what you'd expect.
 //
-// Rather than returning the number of bytes written to the output
-// stream, it returns the nubmer of bytes from p that it successfully
-// handled.  This distinction is because *ReEncoder transforms the
-// data written to it, and the number of bytes written may be wildly
-// different than the number of bytes handled; and that would break
-// virtually all users of io.Writer.
+// It is worth noting that Write returns the number of bytes consumed
+// from p, not number of bytes written to the output stream.  This
+// distinction that most io.Writer implementations don't need to make,
+// but *ReEncoder does because it transforms the data written to it,
+// and the number of bytes written may be wildly different than the
+// number of bytes handled.
 func (enc *ReEncoder) Write(p []byte) (int, error) {
 	if len(p) == 0 {
 		return 0, nil
@@ -163,7 +167,7 @@ func (enc *ReEncoder) Close() error {
 	return nil
 }
 
-// WriteRune write a single Unicode code point, returning the number
+// WriteRune writes a single Unicode code point, returning the number
 // of bytes written to the output stream and any error.
 //
 // Even when there is no error, the number of bytes written may be
@@ -245,7 +249,7 @@ func (enc *ReEncoder) handleRune(c rune, t internal.RuneType) error {
 		}
 	} else { // speculating
 
-		// conCompress is whether we're 1-up from the leaf;
+		// canCompress is whether we're 1-up from the leaf;
 		// set this *before* the calls to .handleRune.
 		canCompress := enc.handleRuneState.specu.indentFmt.handleRuneState.specu == nil