Various performance and documentation improvements

Author: dchenk

Makefile

@@ -10,7 +10,7 @@ SHELL := /bin/bash
 
 BIN = $(GOBIN)/msgp
 
-.PHONY: clean wipe install get-deps bench all
+.PHONY: fmt clean wipe install get-deps bench all
 
 $(BIN): */*.go
 	@go install ./...
@@ -23,6 +23,9 @@ $(GGEN): ./tests/def.go
 $(MGEN): ./msgp/defs_test.go
 	go generate ./msgp
 
+fmt:
+	gofmt -s -w -e ./
+
 test: all
 	go test -v ./...
 

msgp/errors.go

@@ -5,8 +5,8 @@ import (
 	"reflect"
 )
 
-// ErrShortBytes is returned when the slice being decoded is too short
-// to contain the contents of the message.
+// ErrShortBytes is returned when the slice being decoded is too short to contain
+// the contents of the message.
 var ErrShortBytes error = errShort{}
 
 // A fatal error is only returned if we reach code that should be unreachable.
@@ -30,38 +30,36 @@ type errFatal struct{}
 func (f errFatal) Error() string   { return "msgp: fatal decoding error (unreachable code)" }
 func (f errFatal) Resumable() bool { return false }
 
-// ArrayError is an error returned when decoding a fix-sized array
-// of the wrong size.
+// An ArrayError error is returned when decoding a fix-sized array of the wrong size.
 type ArrayError struct {
-	Wanted uint32
-	Got    uint32
+	Wanted, Got uint32
 }
 
-// Error implements the error interface
+// Error implements the error interface.
 func (a ArrayError) Error() string {
 	return fmt.Sprintf("msgp: wanted array of size %d; got %d", a.Wanted, a.Got)
 }
 
 // Resumable is always true for ArrayErrors.
 func (a ArrayError) Resumable() bool { return true }
 
-// IntOverflow is returned when a call would downcast an integer to a type
+// An IntOverflow error is returned when an operation would downcast an integer to a type
 // with too few bits to hold its value.
 type IntOverflow struct {
 	Value         int64 // the value of the integer
 	FailedBitsize int   // the bit size that the int64 could not fit into
 }
 
-// Error implements the error interface
+// Error implements the error interface.
 func (i IntOverflow) Error() string {
 	return fmt.Sprintf("msgp: %d overflows int%d", i.Value, i.FailedBitsize)
 }
 
 // Resumable is always true for overflows.
 func (i IntOverflow) Resumable() bool { return true }
 
-// UintOverflow is returned when a call would downcast an unsigned integer to
-// a type with too few bits to hold its value
+// A UintOverflow error is returned when an operation would downcast an unsigned integer to
+// a type with too few bits to hold its value.
 type UintOverflow struct {
 	Value         uint64 // value of the uint
 	FailedBitsize int    // the bit size that couldn't fit the value
@@ -122,5 +120,5 @@ type ErrUnsupportedType struct {
 // Error implements error
 func (e *ErrUnsupportedType) Error() string { return fmt.Sprintf("msgp: type %q not supported", e.T) }
 
-// Resumable returns 'true' for ErrUnsupportedType
+// Resumable returns true for ErrUnsupportedType.
 func (e *ErrUnsupportedType) Resumable() bool { return true }

msgp/extension.go

@@ -54,37 +54,30 @@ func (e ExtensionTypeError) Error() string {
 	return fmt.Sprintf("msgp: error decoding extension: wanted type %d; got type %d", e.Want, e.Got)
 }
 
-// Resumable returns 'true' for ExtensionTypeErrors
+// Resumable returns true for ExtensionTypeErrors.
 func (e ExtensionTypeError) Resumable() bool { return true }
 
 func errExt(got int8, wanted int8) error {
 	return ExtensionTypeError{Got: got, Want: wanted}
 }
 
-// Extension is the interface fulfilled
-// by types that want to define their
-// own binary encoding.
+// Extension is the interface implemented by types that want to define their own binary encoding.
 type Extension interface {
-	// ExtensionType should return
-	// a int8 that identifies the concrete
-	// type of the extension. (Types <0 are
-	// officially reserved by the MessagePack
-	// specifications.)
+	// ExtensionType returns an int8 that identifies the extension's concrete type.
+	// (Types <0 are reserved by the MessagePack specification.)
 	ExtensionType() int8
 
-	// Len should return the length
-	// of the data to be encoded
+	// Len returns the length of the data to be encoded.
 	Len() int
 
-	// MarshalBinaryTo should copy
-	// the data into the supplied slice,
-	// assuming that the slice has length Len()
+	// MarshalBinaryTo copies the data into the supplied slice, assuming that the
+	// slice has length Len().
 	MarshalBinaryTo([]byte) error
 
 	UnmarshalBinary([]byte) error
 }
 
-// RawExtension implements the Extension interface
+// RawExtension implements the Extension interface.
 type RawExtension struct {
 	Data []byte
 	Type int8
@@ -93,18 +86,17 @@ type RawExtension struct {
 // ExtensionType implements Extension.ExtensionType, and returns r.Type
 func (r *RawExtension) ExtensionType() int8 { return r.Type }
 
-// Len implements Extension.Len, and returns len(r.Data)
+// Len implements Extension.Len.
 func (r *RawExtension) Len() int { return len(r.Data) }
 
-// MarshalBinaryTo implements Extension.MarshalBinaryTo,
-// and returns a copy of r.Data
+// MarshalBinaryTo implements Extension.MarshalBinaryTo and returns a copy of r.Data.
 func (r *RawExtension) MarshalBinaryTo(d []byte) error {
 	copy(d, r.Data)
 	return nil
 }
 
-// UnmarshalBinary implements Extension.UnmarshalBinary,
-// and sets r.Data to the contents of the provided slice
+// UnmarshalBinary implements Extension.UnmarshalBinary and sets r.Data to the contents
+// of the provided slice.
 func (r *RawExtension) UnmarshalBinary(b []byte) error {
 	if cap(r.Data) >= len(b) {
 		r.Data = r.Data[0:len(b)]
@@ -115,7 +107,7 @@ func (r *RawExtension) UnmarshalBinary(b []byte) error {
 	return nil
 }
 
-// WriteExtension writes an extension type to the writer
+// WriteExtension writes an extension type to the writer.
 func (mw *Writer) WriteExtension(e Extension) error {
 	l := e.Len()
 	var err error
@@ -218,8 +210,7 @@ func (mw *Writer) WriteExtension(e Extension) error {
 	return nil
 }
 
-// peek at the extension type, assuming the next
-// kind to be read is Extension
+// peek at the extension type, assuming the next kind to be read is Extension.
 func (m *Reader) peekExtensionType() (int8, error) {
 	p, err := m.R.Peek(2)
 	if err != nil {
@@ -262,19 +253,16 @@ func peekExtension(b []byte) (int8, error) {
 	return int8(b[size-1]), nil
 }
 
-// ReadExtension reads the next object from the reader
-// as an extension. ReadExtension will fail if the next
-// object in the stream is not an extension, or if
-// e.Type() is not the same as the wire type.
+// ReadExtension reads the next object from the reader as an extension. ReadExtension will fail if
+// the next object in the stream is not an extension, or if e.Type() is not the same as the wire type.
 func (m *Reader) ReadExtension(e Extension) (err error) {
-	var p []byte
-	p, err = m.R.Peek(2)
+
+	p, err := m.R.Peek(2)
 	if err != nil {
 		return
 	}
 	lead := p[0]
-	var read int
-	var off int
+	var read, off int
 	switch lead {
 	case mfixext1:
 		if int8(p[1]) != e.ExtensionType() {

msgp/json.go

@@ -16,12 +16,10 @@ var (
 
 var defuns [_maxtype]func(jsWriter, *Reader) (int, error)
 
-// note: there is an initialization loop if
-// this isn't set up during init()
+// Note: there is an initialization loop if this isn't set up during init()
 func init() {
-	// since none of these functions are inline-able,
-	// there is not much of a penalty to the indirect
-	// call. however, this is best expressed as a jump-table...
+	// Since none of these functions are inline-able, there is not much of a
+	// penalty to the indirect call. However, this is best expressed as a jump-table.
 	defuns = [_maxtype]func(jsWriter, *Reader) (int, error){
 		StrType:        rwString,
 		BinType:        rwBytes,
@@ -40,26 +38,24 @@ func init() {
 	}
 }
 
-// this is the interface
-// used to write json
+// jsWriter is the interface used to write JSON.
 type jsWriter interface {
 	io.Writer
 	io.ByteWriter
 	WriteString(string) (int, error)
 }
 
-// CopyToJSON reads MessagePack from 'src' and copies it
-// as JSON to 'dst' until EOF.
+// CopyToJSON reads MessagePack from src and copies it as JSON to dst until EOF.
 func CopyToJSON(dst io.Writer, src io.Reader) (n int64, err error) {
 	r := NewReader(src)
 	n, err = r.WriteToJSON(dst)
-	freeR(r)
+	readerPool.Put(r)
 	return
 }
 
-// WriteToJSON translates MessagePack from 'r' and writes it as
-// JSON to 'w' until the underlying reader returns io.EOF. It returns
-// the number of bytes written, and an error if it stopped before EOF.
+// WriteToJSON translates MessagePack from r and writes it as JSON to w until the underlying
+// reader returns io.EOF. WriteToJSON returns the number of bytes written, and an error if
+// it stopped before EOF.
 func (r *Reader) WriteToJSON(w io.Writer) (n int64, err error) {
 	var j jsWriter
 	var bf *bufio.Writer
@@ -266,8 +262,7 @@ func rwExtension(dst jsWriter, src *Reader) (n int, err error) {
 		return 0, err
 	}
 
-	// registered extensions can override
-	// the JSON encoding
+	// Registered extensions can override the JSON encoding.
 	if j, ok := extensionReg[et]; ok {
 		var bts []byte
 		e := j()
@@ -410,7 +405,7 @@ func rwBytes(dst jsWriter, src *Reader) (n int, err error) {
 // Below (c) The Go Authors, 2009-2014
 // Subject to the BSD-style license found at http://golang.org
 //
-// see: encoding/json/encode.go:(*encodeState).stringbytes()
+// See: encoding/json/encode.go:(*encodeState).stringbytes()
 func rwquoted(dst jsWriter, s []byte) (n int, err error) {
 	var nn int
 	err = dst.WriteByte('"')