*: Cosmetics

Fix noticed typos, clarify things in a couple of places. Only minor
and documentation changes.

/helped-by @kisielk

encode.go

@@ -53,7 +53,9 @@ type EncoderConfig struct {
 	StrictUnicode bool
 }
 
-// NewEncoder returns a new Encoder struct with default values
+// NewEncoder returns a new Encoder with the default configuration.
+//
+// The encoder will emit pickle stream into w.
 func NewEncoder(w io.Writer) *Encoder {
 	return NewEncoderWithConfig(w, &EncoderConfig{
 		// allow both Python2 and Python3 to decode what ogórek produces by default
@@ -61,7 +63,9 @@ func NewEncoder(w io.Writer) *Encoder {
 	})
 }
 
-// NewEncoderWithConfig is similar to NewEncoder, but allows specifying the encoder configuration.
+// NewEncoderWithConfig is similar to NewEncoder, but returns the encoder with the specified configuration.
+//
+// config must not be nil.
 func NewEncoderWithConfig(w io.Writer, config *EncoderConfig) *Encoder {
 	return &Encoder{w: w, config: config}
 }
@@ -151,7 +155,7 @@ func (e *Encoder) encode(rv reflect.Value) error {
 
 	case reflect.Interface:
 		// recurse until we get a concrete type
-		// could be optmized into a tail call
+		// could be optimized into a tail call
 		return e.encode(rv.Elem())
 
 	case reflect.Ptr:

ogorek.go

@@ -67,7 +67,7 @@ const (
 	// Protocol 2
 
 	opProto    byte = '\x80' // identify pickle protocol
-	opNewobj   byte = '\x81' // build object by applying cls.__new__ to argtuple
+	opNewobj   byte = '\x81' // build object: cls argv -> cls.__new__(*argv)
 	opExt1     byte = '\x82' // push object from extension registry; 1-byte index
 	opExt2     byte = '\x83' // ditto, but 2-byte index
 	opExt4     byte = '\x84' // ditto, but 4-byte index
@@ -93,7 +93,7 @@ const (
 	opAddItems        byte = '\x90' // add items to existing set
 	opFrozenSet       byte = '\x91' // build a frozenset out of mark..top
 	opNewobjEx        byte = '\x92' // build object: cls argv kw -> cls.__new__(*argv, **kw)
-	opStackGlobal     byte = '\x93' // same as OpGlobal but using names on the stacks
+	opStackGlobal     byte = '\x93' // same as opGlobal but using names on the stacks
 	opMemoize         byte = '\x94' // store top of the stack in memo
 	opFrame           byte = '\x95' // indicate the beginning of a new frame
 
@@ -191,12 +191,16 @@ type DecoderConfig struct {
 	StrictUnicode bool
 }
 
-// NewDecoder constructs a new Decoder which will decode the pickle stream in r.
+// NewDecoder returns a new Decoder with the default configuration.
+//
+// The decoder will decode the pickle stream in r.
 func NewDecoder(r io.Reader) *Decoder {
 	return NewDecoderWithConfig(r, &DecoderConfig{})
 }
 
-// NewDecoderWithConfig is similar to NewDecoder, but allows specifying decoder configuration.
+// NewDecoderWithConfig is similar to NewDecoder, but returns decoder with the specified configuration.
+//
+// config must not be nil.
 func NewDecoderWithConfig(r io.Reader, config *DecoderConfig) *Decoder {
 	reader := bufio.NewReader(r)
 	return &Decoder{
@@ -1321,7 +1325,7 @@ func (d *Decoder) readOnlyBuffer() error {
 }
 
 // unquoteChar is like strconv.UnquoteChar, but returns io.ErrUnexpectedEOF
-// instead of strconv.ErrSyntax, when input is prematurely terminted.
+// instead of strconv.ErrSyntax, when input is prematurely terminated.
 //
 // XXX remove if ever something like https://golang.org/cl/37052 is accepted.
 func unquoteChar(s string, quote byte) (value rune, multibyte bool, tail string, err error) {
@@ -1342,7 +1346,7 @@ func unquoteChar(s string, quote byte) (value rune, multibyte bool, tail string,
 
 	// + "0"*9 should make s valid if it was cut, e.g. "\U012" becomes "\U012000000000".
 	// On the other hand, if s was invalid, e.g. "\Uz"
-	// it will remain invaild even with the suffix.
+	// it will remain invalid even with the suffix.
 	_, _, _, err2 := strconv.UnquoteChar(s + "000000000", quote)
 	if err2 == nil {
 		err = io.ErrUnexpectedEOF

ogorek_test.go

@@ -100,7 +100,7 @@ type TestEntry struct {
 //   represents protocol=1, P1_ represents protocol >= 1) must give the pickle data.
 //   Decoding the pickle data must give the object.
 
-// X is syntatic sugar to prepare one TestEntry.
+// X is syntactic sugar to prepare one TestEntry.
 //
 // the entry is tested under both StrictUnicode=n and StrictUnicode=y modes.
 func X(name string, object interface{}, picklev ...TestPickle) TestEntry {
@@ -122,7 +122,7 @@ func Xustrict(name string, object interface{}, picklev ...TestPickle) TestEntry
 	return x
 }
 
-// Xloosy is syntatic sugar to prepare one TestEntry with loosy incoding.
+// Xloosy is syntactic sugar to prepare one TestEntry with loosy encoding.
 //
 // It should be used only if objectIn contains Go structs.
 func Xloosy(name string, objectIn, objectOut interface{}, picklev ...TestPickle) TestEntry {
@@ -794,7 +794,7 @@ func TestDecodeError(t *testing.T) {
 		"}(I1\ns.",                  // EMPTY_DICT + MARK + INT + SETITEM
 		"(Q.",                       // MARK + BINPERSID
 
-		// \r\n should not be read as combind EOL - only \n is
+		// \r\n should not be read as combined EOL - only \n is
 		"L123L\r\n.",
 		"S'abc'\r\n.",