From cf1739b92061a002b5380a8273a8e453f79253f0 Mon Sep 17 00:00:00 2001
From: Michael McLoughlin <mmcloughlin@gmail.com>
Date: Sat, 5 Jan 2019 14:12:50 -0800
Subject: [PATCH] internal/gen: doc exported symbols (#9)

---
 internal/gen/asmtest.go   | 4 ++++
 internal/gen/build.go     | 4 ++++
 internal/gen/ctors.go     | 3 +++
 internal/gen/ctorstest.go | 1 +
 internal/gen/gen.go       | 4 ++++
 internal/gen/godata.go    | 9 +++++++++
 internal/gen/mov.go       | 2 ++
 7 files changed, 27 insertions(+)

diff --git a/internal/gen/asmtest.go b/internal/gen/asmtest.go
index ee43565..148e02c 100644
--- a/internal/gen/asmtest.go
+++ b/internal/gen/asmtest.go
@@ -19,6 +19,10 @@ type asmtest struct {
 	prnt.Generator
 }
 
+// NewAsmTest prints one massive assembly function containing a line for every
+// instruction form in the database. The intention is to pass this to the Go
+// assembler and confirm there are no errors, thus helping to ensure our
+// database is compatible.
 func NewAsmTest(cfg printer.Config) Interface {
 	return &asmtest{cfg: cfg}
 }
diff --git a/internal/gen/build.go b/internal/gen/build.go
index 0b6c4b4..35dbad6 100644
--- a/internal/gen/build.go
+++ b/internal/gen/build.go
@@ -11,6 +11,10 @@ type build struct {
 	prnt.Generator
 }
 
+// NewBuild builds a printer that will generate instruction functions in the
+// build package. Each instruction will have one method on the build.Context
+// type, and a corresponding wrapper operating on the global Context. These
+// functions are thin wrappers around constructors generated by NewCtors.
 func NewBuild(cfg printer.Config) Interface {
 	return GoFmt(&build{cfg: cfg})
 }
diff --git a/internal/gen/ctors.go b/internal/gen/ctors.go
index c7cd726..e7bb61e 100644
--- a/internal/gen/ctors.go
+++ b/internal/gen/ctors.go
@@ -15,6 +15,9 @@ type ctors struct {
 	prnt.Generator
 }
 
+// NewCtors will build instruction constructors. Each constructor will check
+// that the provided operands match one of the allowed instruction forms. If so
+// it will return an Instruction object that can be added to an avo Function.
 func NewCtors(cfg printer.Config) Interface {
 	return GoFmt(&ctors{cfg: cfg})
 }
diff --git a/internal/gen/ctorstest.go b/internal/gen/ctorstest.go
index d117e8e..844a495 100644
--- a/internal/gen/ctorstest.go
+++ b/internal/gen/ctorstest.go
@@ -14,6 +14,7 @@ type ctorstest struct {
 	prnt.Generator
 }
 
+// NewCtorsTest autogenerates tests for the constructors build by NewCtors.
 func NewCtorsTest(cfg printer.Config) Interface {
 	return GoFmt(&ctorstest{cfg: cfg})
 }
diff --git a/internal/gen/gen.go b/internal/gen/gen.go
index c202b83..e33ff1a 100644
--- a/internal/gen/gen.go
+++ b/internal/gen/gen.go
@@ -7,16 +7,20 @@ import (
 	"github.com/mmcloughlin/avo/printer"
 )
 
+// Interface of an instruction code generator.
 type Interface interface {
 	Generate([]inst.Instruction) ([]byte, error)
 }
 
+// Func adapts a function to Interface.
 type Func func([]inst.Instruction) ([]byte, error)
 
+// Generate calls f.
 func (f Func) Generate(is []inst.Instruction) ([]byte, error) {
 	return f(is)
 }
 
+// Builder constructs a code generator.
 type Builder func(printer.Config) Interface
 
 // GoFmt formats Go code produced from the given generator.
diff --git a/internal/gen/godata.go b/internal/gen/godata.go
index 221c374..1091925 100644
--- a/internal/gen/godata.go
+++ b/internal/gen/godata.go
@@ -11,6 +11,9 @@ type godata struct {
 	prnt.Generator
 }
 
+// NewGoData writes a Go variable containing the instructions database. This is
+// intended to provide a more friendly version of the instruction database,
+// rather than having to use the raw data sources all the time.
 func NewGoData(cfg printer.Config) Interface {
 	return GoFmt(&godata{cfg: cfg})
 }
@@ -71,6 +74,12 @@ type godatatest struct {
 	prnt.Generator
 }
 
+// NewGoDataTest writes a test case to confirm that NewGoData faithfully
+// represented the list. The reason for this is that NewGoData uses custom code
+// to "pretty print" the database so it is somewhat human-readable. In the
+// process we could easily mistakenly print the database incorrectly. This test
+// prints the same slice of instructions with the ugly but correct "%#v" format
+// specifier, and confirms that the two arrays agree.
 func NewGoDataTest(cfg printer.Config) Interface {
 	return GoFmt(&godatatest{cfg: cfg})
 }
diff --git a/internal/gen/mov.go b/internal/gen/mov.go
index 3e0f56d..f3d0dff 100644
--- a/internal/gen/mov.go
+++ b/internal/gen/mov.go
@@ -16,6 +16,8 @@ type mov struct {
 	prnt.Generator
 }
 
+// NewMOV generates a function that will auto-select the correct MOV instruction
+// based on operand types and and sizes.
 func NewMOV(cfg printer.Config) Interface {
 	return GoFmt(&mov{cfg: cfg})
 }