Documented all exported types, functions, and interfaces

Summary:
Wrote inline documentation for all the things.

Fixes T168000

Test Plan: Execute `godoc -http=:6060` and proofread all the things.

Reviewers: thcipriani, hashar, #release-engineering-team, demon

Reviewed By: thcipriani, #release-engineering-team, demon

Tags: #release-engineering-team

Maniphest Tasks: T168000

Differential Revision: https://phabricator.wikimedia.org/D841

2 files changed, 74 insertions, 17 deletions

diff --git a/build/instructions.go b/build/instructions.go
index 41c959d..3035b9f 100644
--- a/build/instructions.go
+++ b/build/instructions.go
@@ -1,3 +1,7 @@
+// Package build defines types and interfaces that could potentially be
+// compiled to various external build-tool scripts but share a general
+// internal abstraction and rules for escaping.
+//
 package build
 
 import (
@@ -7,15 +11,28 @@ import (
 	"strings"
 )
 
+// Instruction defines a common interface that all concrete build types must
+// implement.
+//
 type Instruction interface {
 	Compile() []string
 }
 
+// Run is a concrete build instruction for passing any number of arguments to
+// a shell command.
+//
+// The command string may contain inner argument placeholders using the "%s"
+// format verb and will be appended with the quoted values of any arguments
+// that remain after interpolation of the command string.
+//
 type Run struct {
-	Command   string
-	Arguments []string
+	Command   string   // command string (e.g. "useradd -d %s -u %s")
+	Arguments []string // command arguments both inner and final (e.g. ["/home/user", "123", "user"])
 }
 
+// Compile quotes all arguments, interpolates the command string with inner
+// arguments, and appends the final arguments.
+//
 func (run Run) Compile() []string {
 	numInnerArgs := strings.Count(run.Command, `%`) - strings.Count(run.Command, `%%`)
 	command := sprintf(run.Command, run.Arguments[0:numInnerArgs])
@@ -27,10 +44,16 @@ func (run Run) Compile() []string {
 	return []string{command}
 }
 
+// RunAll is a concrete build instruction for declaring multiple Run
+// instructions that will be executed together in a `cmd1 && cmd2` chain.
+//
 type RunAll struct {
-	Runs []Run
+	Runs []Run // multiple Run instructions to be executed together
 }
 
+// Compile concatenates all individually compiled Run instructions into a
+// single command.
+//
 func (runAll RunAll) Compile() []string {
 	commands := make([]string, len(runAll.Runs))
 
@@ -41,47 +64,72 @@ func (runAll RunAll) Compile() []string {
 	return []string{strings.Join(commands, " && ")}
 }
 
+// Copy is a concrete build instruction for copying source files/directories
+// from the build host into the image.
+//
 type Copy struct {
-	Sources     []string
-	Destination string
+	Sources     []string // source file/directory paths
+	Destination string   // destination path
 }
 
+// Compile quotes the defined source files/directories and destination.
+//
 func (copy Copy) Compile() []string {
 	return append(quoteAll(copy.Sources), quote(copy.Destination))
 }
 
+// CopyFrom is a concrete build instruction for copying source
+// files/directories from one variant image to another.
+//
 type CopyFrom struct {
-	From string
+	From string // source variant name
 	Copy
 }
 
+// Compile returns the variant name unquoted and all quoted Copy instruction
+// fields.
+//
 func (cf CopyFrom) Compile() []string {
 	return append([]string{cf.From}, cf.Copy.Compile()...)
 }
 
+// Env is a concrete build instruction for declaring a container's runtime
+// environment variables.
+//
 type Env struct {
-	Definitions map[string]string
+	Definitions map[string]string // number of key/value pairs
 }
 
+// Compile returns the key/value pairs as a number of `key="value"` strings
+// where the values are properly quoted and the slice is ordered by the keys.
+//
 func (env Env) Compile() []string {
 	return compileSortedKeyValues(env.Definitions)
 }
 
-// Label represents a number of meta-data key/value pairs
+// Label is a concrete build instruction for declaring a number of meta-data
+// key/value pairs to be included in the image.
+//
 type Label struct {
-	Definitions map[string]string
+	Definitions map[string]string // number of meta-data key/value pairs
 }
 
-// Compile returns the label key/value pairs as a number of `key="value"`
-// strings where the values are properly quoted
+// Compile returns the key/value pairs as a number of `key="value"` strings
+// where the values are properly quoted and the slice is ordered by the keys.
+//
 func (label Label) Compile() []string {
 	return compileSortedKeyValues(label.Definitions)
 }
 
+// Volume is a concrete build instruction for defining a volume mount point
+// within the container.
+//
 type Volume struct {
-	Path string
+	Path string // volume/mount path
 }
 
+// Compile returns the quoted volume path.
+//
 func (vol Volume) Compile() []string {
 	return []string{quote(vol.Path)}
 }
diff --git a/build/phases.go b/build/phases.go
index 02e84e4..3480927 100644
--- a/build/phases.go
+++ b/build/phases.go
@@ -1,15 +1,24 @@
 package build
 
+// Phase enum type
 type Phase int
 
+// Distinct build phases that each compiler implementation should pass to
+// PhaseCompileable configuration (in the order they are defined here) to
+// allow for dependency injection during compilation.
+//
 const (
-	PhasePrivileged Phase = iota
-	PhasePrivilegeDropped
-	PhasePreInstall
-	PhaseInstall
-	PhasePostInstall
+	PhasePrivileged       Phase = iota // first, copies/execution done as root
+	PhasePrivilegeDropped              // second, copies/execution done as unprivileged user from here on
+	PhasePreInstall                    // third, before application files and artifacts are copied
+	PhaseInstall                       // fourth, application files and artifacts are copied
+	PhasePostInstall                   // fifth, after application files and artifacts are copied
 )
 
+// PhaseCompileable defines and interface that all configuration types should
+// implement if they want to inject build instructions into any of the defined
+// build phases.
+//
 type PhaseCompileable interface {
 	InstructionsForPhase(phase Phase) []Instruction
 }