commentary

rootfs/rootfs.go

@@ -27,14 +27,21 @@ var (
 	errBadManifest = errors.New("bad or missing manifest.json")
 )
 
-type dockerManifestJSON []struct {
-	Layers []string `json:"Layers"`
-}
-
-// RootFS accepts a docker layer tarball and flattens it.
-type RootFS struct {
+type (
+	// RootFS accepts a docker layer tarball and flattens it.
+	RootFS struct {
 		rd io.ReadSeeker
-}
+	}
+
+	dockerManifestJSON []struct {
+		Layers []string `json:"Layers"`
+	}
+
+	nameOffset struct {
+		name   string
+		offset int64
+	}
+)
 
 // New creates a new RootFS'er.
 func New(rd io.ReadSeeker) *RootFS {
@@ -86,10 +93,6 @@ func (r *RootFS) WriteTo(w io.Writer) (n int64, err error) {
 		return n, errBadManifest
 	}
 
-	type nameOffset struct {
-		name   string
-		offset int64
-	}
 	// enumerate layers the way they would be laid down in the image
 	layers := make([]nameOffset, len(layerOffsets))
 	for i, name := range manifest[0].Layers {
@@ -233,7 +236,12 @@ func whiteoutDirs(whreaddir map[string]int, nlayers int) []*tree {
 	return ret
 }
 
-// openTargz creates a tar reader from a targzip or tar
+// openTargz creates a tar reader from a targzip or tar.
+//
+// We may be looking at magic values for tar and/or gzip,
+// which would mean "cleaner" code (e.g. no proxyWriter),
+// but that would mean re-implementing gzip.readHeader(),
+// which is ... already in stdlib.
 func openTargz(r io.Reader) (*tar.Reader, func() error) {
 	hdrbuf := &bytes.Buffer{}
 	hdrw := &proxyWriter{w: hdrbuf}
@@ -247,11 +255,13 @@ func openTargz(r io.Reader) (*tar.Reader, func() error) {
 }
 
 // proxyWriter is a pass-through writer. Its underlying writer can be changed
-// on-the-fly.
+// on-the-fly. Useful when there is a stream that needs to be discarded (change
+// the underlying writer to, say, ioutil.Discard).
 type proxyWriter struct {
 	w io.Writer
 }
 
+// Write writes a slice to the underlying w.
 func (pw *proxyWriter) Write(p []byte) (int, error) {
 	return pw.w.Write(p)
 }