From 88eff53893aa28dccbcd2b555b89e8546159efd5 Mon Sep 17 00:00:00 2001
From: Michael McLoughlin <mmcloughlin@gmail.com>
Date: Fri, 4 Jan 2019 19:03:02 -0800
Subject: [PATCH] printer: doc for exported symbols

Updates #9
---
 printer/goasm.go        |  1 +
 printer/printer.go      | 20 ++++++++++++++++++--
 printer/printer_test.go | 31 +++++++++++++++++++++++++++++++
 printer/stubs.go        |  1 +
 4 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 printer/printer_test.go

diff --git a/printer/goasm.go b/printer/goasm.go
index b517c18..a36ab86 100644
--- a/printer/goasm.go
+++ b/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}
 }
diff --git a/printer/printer.go b/printer/printer.go
index 76cc493..35d17c2 100644
--- a/printer/printer.go
+++ b/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())
 }
diff --git a/printer/printer_test.go b/printer/printer_test.go
new file mode 100644
index 0000000..c2fe67f
--- /dev/null
+++ b/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.
+}
diff --git a/printer/stubs.go b/printer/stubs.go
index 2756eee..6ef5ade 100644
--- a/printer/stubs.go
+++ b/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}
 }