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, 40 insertions, 3 deletions

diff --git a/docker/compiler.go b/docker/compiler.go
index 0a2120b..2823777 100644
--- a/docker/compiler.go
+++ b/docker/compiler.go
@@ -1,3 +1,6 @@
+// Package docker implements a compiler for turning Blubber configuration into
+// a valid single- or multi-stage Dockerfile.
+//
 package docker
 
 import (
@@ -9,7 +12,11 @@ import (
 	"phabricator.wikimedia.org/source/blubber/meta"
 )
 
-// Compile blubber yaml file into Dockerfile
+// Compile takes a parsed config.Config and a configured variant name and
+// returns the bytes of a resulting Dockerfile. In the case where artifacts
+// are defined or the shorthand "copies" configured is set, a multi-stage
+// Dockerfile will be returned.
+//
 func Compile(cfg *config.Config, variant string) (*bytes.Buffer, error) {
 	buffer := new(bytes.Buffer)
 
diff --git a/docker/instructions.go b/docker/instructions.go
index eba6731..f362814 100644
--- a/docker/instructions.go
+++ b/docker/instructions.go
@@ -8,6 +8,11 @@ import (
 	"phabricator.wikimedia.org/source/blubber/build"
 )
 
+// NewDockerInstruction takes a general internal build.Instruction and returns
+// a corresponding compilable Docker specific instruction. The given internal
+// instruction is partially compiled at this point by calling Compile() which
+// applies its own logic for escaping arguments, etc.
+//
 func NewDockerInstruction(instruction build.Instruction) (DockerInstruction, error) {
 	switch instruction.(type) {
 	case build.Run, build.RunAll:
@@ -39,6 +44,8 @@ func NewDockerInstruction(instruction build.Instruction) (DockerInstruction, err
 	return nil, errors.New("Unable to create DockerInstruction")
 }
 
+// DockerInstruction defines an interface for instruction compilation.
+//
 type DockerInstruction interface {
 	Compile() string
 	Arguments() []string
@@ -52,24 +59,36 @@ func (di abstractDockerInstruction) Arguments() []string {
 	return di.arguments
 }
 
+// DockerRun compiles into a RUN instruction.
+//
 type DockerRun struct{ abstractDockerInstruction }
 
+// Compile compiles RUN instructions.
+//
 func (dr DockerRun) Compile() string {
 	return fmt.Sprintf(
 		"RUN %s\n",
 		join(dr.arguments, ""))
 }
 
+// DockerCopy compiles into a COPY instruction.
+//
 type DockerCopy struct{ abstractDockerInstruction }
 
+// Compile compiles COPY instructions.
+//
 func (dc DockerCopy) Compile() string {
 	return fmt.Sprintf(
 		"COPY [%s]\n",
 		join(dc.arguments, ", "))
 }
 
+// DockerCopyFrom compiles into a COPY --from instruction.
+//
 type DockerCopyFrom struct{ abstractDockerInstruction }
 
+// Compile compiles COPY --from instructions.
+//
 func (dcf DockerCopyFrom) Compile() string {
 	return fmt.Sprintf(
 		"COPY --from=%s [%s]\n",
@@ -77,26 +96,37 @@ func (dcf DockerCopyFrom) Compile() string {
 		join(dcf.arguments[1:], ", "))
 }
 
+// DockerEnv compiles into a ENV instruction.
+//
 type DockerEnv struct{ abstractDockerInstruction }
 
+// Compile compiles ENV instructions.
+//
 func (de DockerEnv) Compile() string {
 	return fmt.Sprintf(
 		"ENV %s\n",
 		join(de.arguments, " "))
 }
 
-// DockerLabel represents a concrete LABEL instruction
+// DockerLabel compiles into a LABEL instruction.
+//
 type DockerLabel struct{ abstractDockerInstruction }
 
-// Compile returns multiple key="value" arguments as a single LABEL string
+// Compile returns multiple key="value" arguments as a single LABEL
+// instruction.
+//
 func (dl DockerLabel) Compile() string {
 	return fmt.Sprintf(
 		"LABEL %s\n",
 		join(dl.arguments, " "))
 }
 
+// DockerVolume compiles into a VOLUME instruction.
+//
 type DockerVolume struct{ abstractDockerInstruction }
 
+// Compile compiles VOLUME instructions.
+//
 func (dv DockerVolume) Compile() string {
 	return fmt.Sprintf(
 		"VOLUME [%s]\n",