Documentation and test improvements

Author: dchenk

Makefile

@@ -1,5 +1,5 @@
-# NOTE: This Makefile is only necessary if you would
-# like to help develop the msgp tool or library.
+# This Makefile is necessary only if you want to help
+# develop the msgp tool or library.
 # You can still install msgp with `go get` or `go install`.
 
 GGEN = ./tests/def_gen.go ./tests/def_gen_test.go

gen/run.go

@@ -1,5 +1,5 @@
-// This package is the tool msgp uses to generate Go code for the types in your program that you
-// want to serialize to and from the MessagePack format. The package is designed to be usable by
+// Package gen is the tool msgp uses to generate Go code for the types in your program that you
+// want to serialize to and from the MessagePack format. This package is designed to be usable by
 // both the main.go file at the root of this repository (installed as a command line tool that is
 // called by the `go generate` command) and by external programs that import the package.
 //
@@ -11,7 +11,7 @@
 //
 //  import "github.com/dchenk/msgp/gen"
 //
-//  err := gen.Run("path/to/myfile.go", gen.Size|gen.Marshal|gen.Unmarshal|gen.Test, false)
+//  err := gen.Run("path/to/my_file.go", gen.Size|gen.Marshal|gen.Unmarshal|gen.Test, false)
 //
 package gen
 
@@ -90,7 +90,7 @@ func RunData(srcPath string, mode Method, unexported bool) (mainBuf *bytes.Buffe
 	}
 
 	fmt.Println(chalk.Magenta.Color("======= MessagePack Code Generating ======="))
-	fmt.Printf(chalk.Magenta.Color(">>> Input: %q\n"), srcPath)
+	fmt.Printf(chalk.Magenta.Color("   Input: %s\n"), srcPath)
 
 	mainBuf = bytes.NewBuffer(make([]byte, 0, 4096))
 	writePkgHeader(mainBuf, s.pkg)
@@ -101,7 +101,7 @@ func RunData(srcPath string, mode Method, unexported bool) (mainBuf *bytes.Buffe
 			// If the import has an alias, include it (imp.Path.Value is a quoted string).
 			// But do not include the import if its alias is the blank identifier.
 			if imp.Name.Name == "_" {
-				fmt.Printf(chalk.Blue.Color("Not including import %s with blank identifier as alias\n"), imp.Path.Value)
+				fmt.Printf(chalk.Blue.Color("Not including import %s with blank identifier as alias.\n"), imp.Path.Value)
 			} else {
 				mainImports = append(mainImports, imp.Name.Name+" "+imp.Path.Value)
 			}
@@ -123,7 +123,7 @@ func RunData(srcPath string, mode Method, unexported bool) (mainBuf *bytes.Buffe
 
 	writeImportHeader(mainBuf, mainImports)
 
-	// Write the test file if it's needed.
+	// Write the test file if it's desired.
 	if mode&Test == Test {
 		testsBuf = bytes.NewBuffer(make([]byte, 0, 4096))
 		writePkgHeader(testsBuf, s.pkg)
@@ -147,7 +147,7 @@ func formatWrite(fileName string, data []byte) error {
 	if err != nil {
 		return err
 	}
-	fmt.Printf(chalk.Magenta.Color(">>> Writing file \"%s\"\n"), fileName)
+	fmt.Printf(chalk.Magenta.Color("   Writing file: %s\n"), fileName)
 	return ioutil.WriteFile(fileName, out, 0600)
 }
 

msgp/defs.go

@@ -1,8 +1,8 @@
-// Package msgp is the support library for the msgp code generator (http://github.com/dchenk/msgp).
+// Package msgp is the runtime support library for the msgp code generator (http://github.com/dchenk/msgp).
 //
 // This package defines the utilities used by the msgp code generator for encoding and decoding MessagePack
-// from []byte and io.Reader/io.Writer types. Much of this package is devoted to helping the msgp code
-// generator implement the Marshaler/Unmarshaler and Encoder/Decoder interfaces to avoid runtime reflection.
+// from []byte and io.Reader/io.Writer types. Most things here are intended to be used only in programs that
+// use the msgp code generator, the point being to avoid runtime reflection.
 //
 // This package defines four families of functions:
 // 	- AppendXxxx() appends an object to a []byte in MessagePack encoding.

msgp/defs_test.go

@@ -2,7 +2,7 @@ package msgp_test
 
 //go:generate msgp -o=defs_gen_test.go -tests=false
 
-type Blobs []Blob
+type Blobs []Blob // needed separately for Msgsize()
 
 type Blob struct {
 	Name   string  `msgp:"name"`

msgp/extension.go

@@ -16,7 +16,7 @@ const (
 	TimeExtension = 5
 )
 
-// our extensions live here
+// extensionReg contains registered extensions.
 var extensionReg = make(map[int8]func() Extension)
 
 // RegisterExtension registers extensions so that they can be initialized and returned

msgp/file_test.go

@@ -1,5 +1,3 @@
-// +build linux darwin dragonfly freebsd netbsd openbsd
-
 package msgp_test
 
 import (
@@ -32,32 +30,40 @@ func TestReadWriteFile(t *testing.T) {
 
 	t.Parallel()
 
-	f, err := os.Create("tmpfile")
+	fname := "tmpfile"
+	f, err := os.Create(fname)
 	if err != nil {
 		t.Fatal(err)
 	}
 	defer func() {
 		f.Close()
-		os.Remove("tmpfile")
+		os.Remove(fname)
 	}()
 
 	data := make([]byte, 1024*1024)
-	rand.Read(data)
+	if _, err = rand.Read(data); err != nil {
+		t.Fatalf("rand reader: %v", err)
+	}
 
-	err = msgp.WriteFile(rawBytes(data), f)
+	if err = msgp.WriteFile(rawBytes(data), f); err != nil {
+		t.Fatalf("writing file: %v", err)
+	}
+	if err = f.Close(); err != nil {
+		t.Fatalf("could not close file; %v", err)
+	}
+
+	f, err = os.Open(fname)
 	if err != nil {
-		t.Fatal(err)
+		t.Fatalf("could not open written file; %v", err)
 	}
 
 	var out rawBytes
-	f.Seek(0, os.SEEK_SET) // TODO: SEEK_SET is deprecated
-	err = msgp.ReadFile(&out, f)
-	if err != nil {
-		t.Fatal(err)
+	if err = msgp.ReadFile(&out, f); err != nil {
+		t.Fatalf("reading file: %v", err)
 	}
 
 	if !bytes.Equal([]byte(out), data) {
-		t.Fatal("Input and output not equal.")
+		t.Fatal("Input not equal to output.")
 	}
 
 }
@@ -79,10 +85,10 @@ func BenchmarkWriteReadFile(b *testing.B) {
 	if err != nil {
 		b.Fatal(err)
 	}
-	defer func(f *os.File, name string) {
+	defer func() {
 		f.Close()
-		os.Remove(name)
-	}(f, fname)
+		os.Remove(fname)
+	}()
 
 	data := make(Blobs, b.N)
 
@@ -95,6 +101,7 @@ func BenchmarkWriteReadFile(b *testing.B) {
 
 	b.SetBytes(int64(data.Msgsize() / b.N))
 	b.ResetTimer()
+
 	err = msgp.WriteFile(data, f)
 	if err != nil {
 		b.Fatal(err)
@@ -103,4 +110,5 @@ func BenchmarkWriteReadFile(b *testing.B) {
 	if err != nil {
 		b.Fatal(err)
 	}
+
 }