printer: doc for exported symbols

Updates #9

printer/goasm.go

@@ -17,6 +17,7 @@ type goasm struct {
 	prnt.Generator
 }
 
+// NewGoAsm constructs a printer for writing Go assembly files.
 func NewGoAsm(cfg Config) Printer {
 	return &goasm{cfg: cfg}
 }

printer/printer.go

@@ -1,3 +1,4 @@
+// Package printer implements printing of avo files in various formats.
 package printer
 
 import (
@@ -10,18 +11,29 @@ import (
 	"github.com/mmcloughlin/avo/internal/stack"
 )
 
+// Printer can produce output for an avo File.
 type Printer interface {
 	Print(*avo.File) ([]byte, error)
 }
 
+// Builder can construct a printer.
 type Builder func(Config) Printer
 
+// Config represents general printing configuration.
 type Config struct {
-	Name string
+	// Command-line arguments passed to the generator. If provided, this will be
+	// included in a code generation warning.
 	Argv []string
-	Pkg  string
+
+	// Name of the code generator.
+	Name string
+
+	// Name of Go package the generated code will belong to.
+	Pkg string
 }
 
+// NewDefaultConfig produces a config with Name "avo".
+// The package name is guessed from the current directory.
 func NewDefaultConfig() Config {
 	return Config{
 		Name: "avo",
@@ -29,6 +41,8 @@ func NewDefaultConfig() Config {
 	}
 }
 
+// NewArgvConfig constructs a Config from os.Args.
+// The package name is guessed from the current directory.
 func NewArgvConfig() Config {
 	return Config{
 		Argv: os.Args,
@@ -53,6 +67,7 @@ func NewGoRunConfig() Config {
 	}
 }
 
+// GeneratedBy returns a description of the code generator.
 func (c Config) GeneratedBy() string {
 	if c.Argv == nil {
 		return c.Name
@@ -60,6 +75,7 @@ func (c Config) GeneratedBy() string {
 	return fmt.Sprintf("command: %s", strings.Join(c.Argv, " "))
 }
 
+// GeneratedWarning returns text for a code generation warning. Conforms to https://golang.org/s/generatedcode.
 func (c Config) GeneratedWarning() string {
 	return fmt.Sprintf("Code generated by %s. DO NOT EDIT.", c.GeneratedBy())
 }

printer/printer_test.go

@@ -0,0 +1,31 @@
+package printer_test
+
+import (
+	"fmt"
+
+	"github.com/mmcloughlin/avo/printer"
+)
+
+func ExampleConfig_GeneratedWarning() {
+	// Default configuration named "avo".
+	cfg := printer.NewDefaultConfig()
+	fmt.Println(cfg.GeneratedWarning())
+
+	// Name can be customized.
+	cfg = printer.Config{
+		Name: "mildred",
+	}
+	fmt.Println(cfg.GeneratedWarning())
+
+	// Argv takes precedence.
+	cfg = printer.Config{
+		Argv: []string{"echo", "hello", "world"},
+		Name: "mildred",
+	}
+	fmt.Println(cfg.GeneratedWarning())
+
+	// Output:
+	// Code generated by avo. DO NOT EDIT.
+	// Code generated by mildred. DO NOT EDIT.
+	// Code generated by command: echo hello world. DO NOT EDIT.
+}

printer/stubs.go

@@ -10,6 +10,7 @@ type stubs struct {
 	prnt.Generator
 }
 
+// NewStubs constructs a printer for writing stub function declarations.
 func NewStubs(cfg Config) Printer {
 	return &stubs{cfg: cfg}
 }