From 4f388e0e27f67278629d1b31b71c24aa75cc48bb Mon Sep 17 00:00:00 2001
From: Derek McGowan <derek@mcgstyle.net>
Date: Wed, 12 Jul 2017 13:57:51 -0700
Subject: [PATCH] Add documentation to rootfs functions

Clarifies role of varies rootfs functions as well as their return values.

Signed-off-by: Derek McGowan <derek@mcgstyle.net>
---
 rootfs/apply.go | 12 ++++++++++++
 rootfs/diff.go  | 15 ++++++++-------
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/rootfs/apply.go b/rootfs/apply.go
index ac2ba1040..32ee1317c 100644
--- a/rootfs/apply.go
+++ b/rootfs/apply.go
@@ -14,15 +14,24 @@ import (
 	"golang.org/x/net/context"
 )
 
+// Applier is used to apply a descriptor of a layer diff on top of mounts.
 type Applier interface {
 	Apply(context.Context, ocispec.Descriptor, []mount.Mount) (ocispec.Descriptor, error)
 }
 
+// Layer represents the descriptors for a layer diff. These descriptions
+// include the descriptor for the uncompressed tar diff as well as a blob
+// used to transport that tar. The blob descriptor may or may not describe
+// a compressed object.
 type Layer struct {
 	Diff ocispec.Descriptor
 	Blob ocispec.Descriptor
 }
 
+// ApplyLayers applies all the layers using the given snapshotter and applier.
+// The returned result is a chain id digest representing all the applied layers.
+// Layers are applied in order they are given, making the first layer the
+// bottom-most layer in the layer chain.
 func ApplyLayers(ctx context.Context, layers []Layer, sn snapshot.Snapshotter, a Applier) (digest.Digest, error) {
 	var chain []digest.Digest
 	for _, layer := range layers {
@@ -36,6 +45,9 @@ func ApplyLayers(ctx context.Context, layers []Layer, sn snapshot.Snapshotter, a
 	return identity.ChainID(chain), nil
 }
 
+// ApplyLayer applies a single layer on top of the given provided layer chain,
+// using the provided snapshotter and applier. If the layer was unpacked true
+// is returned, if the layer already exists false is returned.
 func ApplyLayer(ctx context.Context, layer Layer, chain []digest.Digest, sn snapshot.Snapshotter, a Applier) (bool, error) {
 	var (
 		parent  = identity.ChainID(chain)
diff --git a/rootfs/diff.go b/rootfs/diff.go
index 05d02c90b..c83ab4f1f 100644
--- a/rootfs/diff.go
+++ b/rootfs/diff.go
@@ -3,23 +3,24 @@ package rootfs
 import (
 	"fmt"
 
-	"github.com/containerd/containerd/content"
 	"github.com/containerd/containerd/mount"
 	"github.com/containerd/containerd/snapshot"
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"golang.org/x/net/context"
 )
 
+// MountDiffer computes the difference between two mounts and returns a
+// descriptor for the computed diff. The provided ref can be used to track
+// the content creation of the diff and media type is used to determine the
+// format of the created content.
 type MountDiffer interface {
 	DiffMounts(ctx context.Context, lower, upper []mount.Mount, media, ref string) (ocispec.Descriptor, error)
 }
 
-type DiffOptions struct {
-	MountDiffer
-	content.Store
-	snapshot.Snapshotter
-}
-
+// Diff creates a layer diff for the given snapshot identifier from the parent
+// of the snapshot. A content ref is provided to track the progress of the
+// content creation and the provided snapshotter and mount differ are used
+// for calculating the diff. The descriptor for the layer diff is returned.
 func Diff(ctx context.Context, snapshotID, contentRef string, sn snapshot.Snapshotter, md MountDiffer) (ocispec.Descriptor, error) {
 	info, err := sn.Stat(ctx, snapshotID)
 	if err != nil {