internal/gen: doc exported symbols (#9)

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}
 }

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})
 }

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})
 }

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})
 }

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.

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})
 }

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})
 }