pass: doc exported symbols (#9)

pass/pass.go

@@ -1,3 +1,4 @@
+// Package pass implements processing passes on avo Files.
 package pass
 
 import (
@@ -7,6 +8,8 @@ import (
 	"github.com/mmcloughlin/avo/printer"
 )
 
+// Compile pass compiles an avo file. Upon successful completion the avo file
+// may be printed to Go assembly.
 var Compile = Concat(
 	FunctionPass(LabelTarget),
 	FunctionPass(CFG),
@@ -17,18 +20,24 @@ var Compile = Concat(
 	Func(IncludeTextFlagHeader),
 )
 
+// Interface for a processing pass.
 type Interface interface {
 	Execute(*avo.File) error
 }
 
+// Func adapts a function to the pass Interface.
 type Func func(*avo.File) error
 
+// Execute calls p.
 func (p Func) Execute(f *avo.File) error {
 	return p(f)
 }
 
+// FunctionPass is a convenience for implementing a full file pass with a
+// function that operates on each avo Function independently.
 type FunctionPass func(*avo.Function) error
 
+// Execute calls p on every function in the file. Exits on the first error.
 func (p FunctionPass) Execute(f *avo.File) error {
 	for _, fn := range f.Functions() {
 		if err := p(fn); err != nil {
@@ -38,6 +47,7 @@ func (p FunctionPass) Execute(f *avo.File) error {
 	return nil
 }
 
+// Concat returns a pass that executes the given passes in order, stopping on the first error.
 func Concat(passes ...Interface) Interface {
 	return Func(func(f *avo.File) error {
 		for _, p := range passes {
@@ -49,11 +59,13 @@ func Concat(passes ...Interface) Interface {
 	})
 }
 
+// Output pass prints a file.
 type Output struct {
 	Writer  io.WriteCloser
 	Printer printer.Printer
 }
 
+// Execute prints f with the configured Printer and writes output to Writer.
 func (o *Output) Execute(f *avo.File) error {
 	b, err := o.Printer.Print(f)
 	if err != nil {