From 5a5f9e93e9134378ffb5d0294577875a0d8c1937 Mon Sep 17 00:00:00 2001
From: John Howard <John.Howard@microsoft.com>
Date: Thu, 27 Aug 2015 15:46:00 -0700
Subject: [PATCH] Windows: Revendor HCSShim with godoc

Signed-off-by: John Howard <John.Howard@microsoft.com>
---
 hack/vendor.sh                                               | 2 +-
 vendor/src/github.com/microsoft/hcsshim/activatelayer.go     | 4 ++++
 vendor/src/github.com/microsoft/hcsshim/copylayer.go         | 4 ++++
 .../src/github.com/microsoft/hcsshim/createcomputesystem.go  | 4 +++-
 vendor/src/github.com/microsoft/hcsshim/createlayer.go       | 2 ++
 vendor/src/github.com/microsoft/hcsshim/createprocess.go     | 2 +-
 .../src/github.com/microsoft/hcsshim/createsandboxlayer.go   | 4 ++++
 vendor/src/github.com/microsoft/hcsshim/deactivatelayer.go   | 1 +
 vendor/src/github.com/microsoft/hcsshim/destroylayer.go      | 2 ++
 vendor/src/github.com/microsoft/hcsshim/exportlayer.go       | 5 +++++
 vendor/src/github.com/microsoft/hcsshim/getlayermountpath.go | 4 ++++
 .../src/github.com/microsoft/hcsshim/getsharedbaseimages.go  | 3 +++
 vendor/src/github.com/microsoft/hcsshim/importlayer.go       | 4 ++++
 vendor/src/github.com/microsoft/hcsshim/layerexists.go       | 2 ++
 vendor/src/github.com/microsoft/hcsshim/nametoguid.go        | 3 +++
 vendor/src/github.com/microsoft/hcsshim/preparelayer.go      | 5 +++++
 vendor/src/github.com/microsoft/hcsshim/resizeconsole.go     | 2 ++
 .../github.com/microsoft/hcsshim/shutdowncomputesystem.go    | 3 ++-
 .../src/github.com/microsoft/hcsshim/startcomputesystem.go   | 3 ++-
 .../github.com/microsoft/hcsshim/terminatecomputesystem.go   | 2 +-
 vendor/src/github.com/microsoft/hcsshim/terminateprocess.go  | 2 +-
 vendor/src/github.com/microsoft/hcsshim/unpreparelayer.go    | 2 ++
 22 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/hack/vendor.sh b/hack/vendor.sh
index 928e3b725f..1d0e9059ed 100755
--- a/hack/vendor.sh
+++ b/hack/vendor.sh
@@ -14,7 +14,7 @@ clone git github.com/gorilla/context 14f550f51a
 clone git github.com/gorilla/mux e444e69cbd
 clone git github.com/kr/pty 5cf931ef8f
 clone git github.com/mattn/go-sqlite3 b4142c444a8941d0d92b0b7103a24df9cd815e42
-clone git github.com/microsoft/hcsshim da093dac579302d7b413696b96dec0b5e1bce8d4
+clone git github.com/microsoft/hcsshim 7f646aa6b26bcf90caee91e93cde4a80d0d8a83e
 clone git github.com/mistifyio/go-zfs v2.1.1
 clone git github.com/tchap/go-patricia v2.1.0
 clone git golang.org/x/net 3cffabab72adf04f8e3b01c5baf775361837b5fe https://github.com/golang/net.git
diff --git a/vendor/src/github.com/microsoft/hcsshim/activatelayer.go b/vendor/src/github.com/microsoft/hcsshim/activatelayer.go
index a2c096d7a6..dbe3af39f5 100644
--- a/vendor/src/github.com/microsoft/hcsshim/activatelayer.go
+++ b/vendor/src/github.com/microsoft/hcsshim/activatelayer.go
@@ -8,6 +8,10 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// ActivateLayer will find the layer with the given id and mount it's filesystem.
+// For a read/write layer, the mounted filesystem will appear as a volume on the
+// host, while a read-only layer is generally expected to be a no-op.
+// An activated layer must later be deactivated via DeactivateLayer.
 func ActivateLayer(info DriverInfo, id string) error {
 	title := "hcsshim::ActivateLayer "
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)
diff --git a/vendor/src/github.com/microsoft/hcsshim/copylayer.go b/vendor/src/github.com/microsoft/hcsshim/copylayer.go
index 1e8fd951bd..5176eecb35 100644
--- a/vendor/src/github.com/microsoft/hcsshim/copylayer.go
+++ b/vendor/src/github.com/microsoft/hcsshim/copylayer.go
@@ -8,6 +8,10 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// CopyLayer performs a commit of the srcId (which is expected to be a read-write
+// layer) into a new read-only layer at dstId.  This requires the full list of
+// on-disk paths to parent layers, provided in parentLayerPaths, in order to
+// complete the commit.
 func CopyLayer(info DriverInfo, srcId, dstId string, parentLayerPaths []string) error {
 	title := "hcsshim::CopyLayer "
 	logrus.Debugf(title+"srcId %s dstId", srcId, dstId)
diff --git a/vendor/src/github.com/microsoft/hcsshim/createcomputesystem.go b/vendor/src/github.com/microsoft/hcsshim/createcomputesystem.go
index 6b2c0e718f..f456c33356 100644
--- a/vendor/src/github.com/microsoft/hcsshim/createcomputesystem.go
+++ b/vendor/src/github.com/microsoft/hcsshim/createcomputesystem.go
@@ -8,7 +8,9 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// CreateComputeSystem creates a container
+// CreateComputeSystem creates a container, initializing its configuration in
+// the Host Compute Service such that it can be started by a call to the
+// StartComputeSystem method.
 func CreateComputeSystem(id string, configuration string) error {
 
 	title := "HCSShim::CreateComputeSystem"
diff --git a/vendor/src/github.com/microsoft/hcsshim/createlayer.go b/vendor/src/github.com/microsoft/hcsshim/createlayer.go
index 3319f3df5b..0ea3c93b47 100644
--- a/vendor/src/github.com/microsoft/hcsshim/createlayer.go
+++ b/vendor/src/github.com/microsoft/hcsshim/createlayer.go
@@ -8,6 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// CreateLayer creates a new, empty, read-only layer on the filesystem based on
+// the parent layer provided.
 func CreateLayer(info DriverInfo, id, parent string) error {
 	title := "hcsshim::CreateLayer "
 	logrus.Debugf(title+"Flavour %s ID %s parent %s", info.Flavour, id, parent)
diff --git a/vendor/src/github.com/microsoft/hcsshim/createprocess.go b/vendor/src/github.com/microsoft/hcsshim/createprocess.go
index 6f0ce91012..c3cd8b9dde 100644
--- a/vendor/src/github.com/microsoft/hcsshim/createprocess.go
+++ b/vendor/src/github.com/microsoft/hcsshim/createprocess.go
@@ -11,7 +11,7 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// processParameters is use to both the input of CreateProcessInComputeSystem
+// CreateProcessParams is used as both the input of CreateProcessInComputeSystem
 // and to convert the parameters to JSON for passing onto the HCS
 type CreateProcessParams struct {
 	ApplicationName  string
diff --git a/vendor/src/github.com/microsoft/hcsshim/createsandboxlayer.go b/vendor/src/github.com/microsoft/hcsshim/createsandboxlayer.go
index 7d2e8640f7..d3175c0e05 100644
--- a/vendor/src/github.com/microsoft/hcsshim/createsandboxlayer.go
+++ b/vendor/src/github.com/microsoft/hcsshim/createsandboxlayer.go
@@ -8,6 +8,10 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// CreateSandboxLayer creates and populates new read-write layer for use by a container.
+// This requires both the id of the direct parent layer, as well as the full list
+// of paths to all parent layers up to the base (and including the direct parent
+// whose id was provided).
 func CreateSandboxLayer(info DriverInfo, layerId, parentId string, parentLayerPaths []string) error {
 	title := "hcsshim::CreateSandboxLayer "
 	logrus.Debugf(title+"layerId %s parentId %s", layerId, parentId)
diff --git a/vendor/src/github.com/microsoft/hcsshim/deactivatelayer.go b/vendor/src/github.com/microsoft/hcsshim/deactivatelayer.go
index 4144138e41..ac76684b7a 100644
--- a/vendor/src/github.com/microsoft/hcsshim/deactivatelayer.go
+++ b/vendor/src/github.com/microsoft/hcsshim/deactivatelayer.go
@@ -8,6 +8,7 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// DeactivateLayer will dismount a layer that was mounted via ActivateLayer.
 func DeactivateLayer(info DriverInfo, id string) error {
 	title := "hcsshim::DeactivateLayer "
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)
diff --git a/vendor/src/github.com/microsoft/hcsshim/destroylayer.go b/vendor/src/github.com/microsoft/hcsshim/destroylayer.go
index 7561cb2cb3..6b6f983c3e 100644
--- a/vendor/src/github.com/microsoft/hcsshim/destroylayer.go
+++ b/vendor/src/github.com/microsoft/hcsshim/destroylayer.go
@@ -8,6 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// DestroyLayer will remove the on-disk files representing the layer with the given
+// id, including that layer's containing folder, if any.
 func DestroyLayer(info DriverInfo, id string) error {
 	title := "hcsshim::DestroyLayer "
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)
diff --git a/vendor/src/github.com/microsoft/hcsshim/exportlayer.go b/vendor/src/github.com/microsoft/hcsshim/exportlayer.go
index dd08dd0b61..a937ac0954 100644
--- a/vendor/src/github.com/microsoft/hcsshim/exportlayer.go
+++ b/vendor/src/github.com/microsoft/hcsshim/exportlayer.go
@@ -8,6 +8,11 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// ExportLayer will create a folder at exportFolderPath and fill that folder with
+// the transport format version of the layer identified by layerId. This transport
+// format includes any metadata required for later importing the layer (using
+// ImportLayer), and requires the full list of parent layer paths in order to
+// perform the export.
 func ExportLayer(info DriverInfo, layerId string, exportFolderPath string, parentLayerPaths []string) error {
 	title := "hcsshim::ExportLayer "
 	logrus.Debugf(title+"flavour %d layerId %s folder %s", info.Flavour, layerId, exportFolderPath)
diff --git a/vendor/src/github.com/microsoft/hcsshim/getlayermountpath.go b/vendor/src/github.com/microsoft/hcsshim/getlayermountpath.go
index 9297f5fbd4..230bcf414d 100644
--- a/vendor/src/github.com/microsoft/hcsshim/getlayermountpath.go
+++ b/vendor/src/github.com/microsoft/hcsshim/getlayermountpath.go
@@ -8,6 +8,10 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// GetLayerMountPath will look for a mounted layer with the given id and return
+// the path at which that layer can be accessed.  This path may be a volume path
+// if the layer is a mounted read-write layer, otherwise it is expected to be the
+// folder path at which the layer is stored.
 func GetLayerMountPath(info DriverInfo, id string) (string, error) {
 	title := "hcsshim::GetLayerMountPath "
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)
diff --git a/vendor/src/github.com/microsoft/hcsshim/getsharedbaseimages.go b/vendor/src/github.com/microsoft/hcsshim/getsharedbaseimages.go
index ba579335c3..a6c4b7bdb1 100644
--- a/vendor/src/github.com/microsoft/hcsshim/getsharedbaseimages.go
+++ b/vendor/src/github.com/microsoft/hcsshim/getsharedbaseimages.go
@@ -8,6 +8,9 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// GetSharedBaseImages will enumerate the images stored in the common central
+// image store and return descriptive info about those images for the purpose
+// of registering them with the graphdriver, graph, and tagstore.
 func GetSharedBaseImages() (imageData string, err error) {
 	title := "hcsshim::GetSharedBaseImages "
 
diff --git a/vendor/src/github.com/microsoft/hcsshim/importlayer.go b/vendor/src/github.com/microsoft/hcsshim/importlayer.go
index 02f85439f1..a214fcd179 100644
--- a/vendor/src/github.com/microsoft/hcsshim/importlayer.go
+++ b/vendor/src/github.com/microsoft/hcsshim/importlayer.go
@@ -8,6 +8,10 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// ImportLayer will take the contents of the folder at importFolderPath and import
+// that into a layer with the id layerId.  Note that in order to correctly populate
+// the layer and interperet the transport format, all parent layers must already
+// be present on the system at the paths provided in parentLayerPaths.
 func ImportLayer(info DriverInfo, layerId string, importFolderPath string, parentLayerPaths []string) error {
 	title := "hcsshim::ImportLayer "
 	logrus.Debugf(title+"flavour %d layerId %s folder %s", info.Flavour, layerId, importFolderPath)
diff --git a/vendor/src/github.com/microsoft/hcsshim/layerexists.go b/vendor/src/github.com/microsoft/hcsshim/layerexists.go
index 143085899e..64e91b943b 100644
--- a/vendor/src/github.com/microsoft/hcsshim/layerexists.go
+++ b/vendor/src/github.com/microsoft/hcsshim/layerexists.go
@@ -8,6 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// LayerExists will return true if a layer with the given id exists and is known
+// to the system.
 func LayerExists(info DriverInfo, id string) (bool, error) {
 	title := "hcsshim::LayerExists "
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)
diff --git a/vendor/src/github.com/microsoft/hcsshim/nametoguid.go b/vendor/src/github.com/microsoft/hcsshim/nametoguid.go
index 433b4fa16c..048e978286 100644
--- a/vendor/src/github.com/microsoft/hcsshim/nametoguid.go
+++ b/vendor/src/github.com/microsoft/hcsshim/nametoguid.go
@@ -8,6 +8,9 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// NameToGuid converts the given string into a GUID using the algorithm in the
+// Host Compute Service, ensuring GUIDs generated with the same string are common
+// across all clients.
 func NameToGuid(name string) (id GUID, err error) {
 	title := "hcsshim::NameToGuid "
 	logrus.Debugf(title+"Name %s", name)
diff --git a/vendor/src/github.com/microsoft/hcsshim/preparelayer.go b/vendor/src/github.com/microsoft/hcsshim/preparelayer.go
index 7aaf5c00f9..d64de06ae5 100644
--- a/vendor/src/github.com/microsoft/hcsshim/preparelayer.go
+++ b/vendor/src/github.com/microsoft/hcsshim/preparelayer.go
@@ -8,6 +8,11 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// PrepareLayer finds a mounted read-write layer matching layerId and enables the
+// the filesystem filter for use on that layer.  This requires the paths to all
+// parent layers, and is necessary in order to view or interact with the layer
+// as an actual filesystem (reading and writing files, creating directories, etc).
+// Disabling the filter must be done via UnprepareLayer.
 func PrepareLayer(info DriverInfo, layerId string, parentLayerPaths []string) error {
 	title := "hcsshim::PrepareLayer "
 	logrus.Debugf(title+"flavour %d layerId %s", info.Flavour, layerId)
diff --git a/vendor/src/github.com/microsoft/hcsshim/resizeconsole.go b/vendor/src/github.com/microsoft/hcsshim/resizeconsole.go
index fcb2379a5f..3456b46ff1 100644
--- a/vendor/src/github.com/microsoft/hcsshim/resizeconsole.go
+++ b/vendor/src/github.com/microsoft/hcsshim/resizeconsole.go
@@ -8,6 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// ResizeConsoleInComputeSystem updates the height and width of the console
+// session for the process with the given id in the container with the given id.
 func ResizeConsoleInComputeSystem(id string, processid uint32, h, w int) error {
 
 	title := "HCSShim::ResizeConsoleInComputeSystem"
diff --git a/vendor/src/github.com/microsoft/hcsshim/shutdowncomputesystem.go b/vendor/src/github.com/microsoft/hcsshim/shutdowncomputesystem.go
index 7a872dc139..a4dc81dedb 100644
--- a/vendor/src/github.com/microsoft/hcsshim/shutdowncomputesystem.go
+++ b/vendor/src/github.com/microsoft/hcsshim/shutdowncomputesystem.go
@@ -8,7 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// ShutdownComputeSystem shuts down a container
+// ShutdownComputeSystem shuts down a container by requesting a shutdown within
+// the container operating system.
 func ShutdownComputeSystem(id string) error {
 
 	var title = "HCSShim::ShutdownComputeSystem"
diff --git a/vendor/src/github.com/microsoft/hcsshim/startcomputesystem.go b/vendor/src/github.com/microsoft/hcsshim/startcomputesystem.go
index 2769917a86..f08d924062 100644
--- a/vendor/src/github.com/microsoft/hcsshim/startcomputesystem.go
+++ b/vendor/src/github.com/microsoft/hcsshim/startcomputesystem.go
@@ -8,7 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// StartComputeSystem starts a container
+// StartComputeSystem starts a container that has previously been created via
+// CreateComputeSystem.
 func StartComputeSystem(id string) error {
 
 	title := "HCSShim::StartComputeSystem"
diff --git a/vendor/src/github.com/microsoft/hcsshim/terminatecomputesystem.go b/vendor/src/github.com/microsoft/hcsshim/terminatecomputesystem.go
index a51d829642..c1aebe4998 100644
--- a/vendor/src/github.com/microsoft/hcsshim/terminatecomputesystem.go
+++ b/vendor/src/github.com/microsoft/hcsshim/terminatecomputesystem.go
@@ -8,7 +8,7 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// TerminateComputeSystem force terminates a container
+// TerminateComputeSystem force terminates a container.
 func TerminateComputeSystem(id string) error {
 
 	var title = "HCSShim::TerminateComputeSystem"
diff --git a/vendor/src/github.com/microsoft/hcsshim/terminateprocess.go b/vendor/src/github.com/microsoft/hcsshim/terminateprocess.go
index 9d3fc0059b..4edc89b9a1 100644
--- a/vendor/src/github.com/microsoft/hcsshim/terminateprocess.go
+++ b/vendor/src/github.com/microsoft/hcsshim/terminateprocess.go
@@ -8,7 +8,7 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// TerminateProcessInComputeSystem kills a process in a running container
+// TerminateProcessInComputeSystem kills a process in a running container.
 func TerminateProcessInComputeSystem(id string, processid uint32) (err error) {
 
 	title := "HCSShim::TerminateProcessInComputeSystem"
diff --git a/vendor/src/github.com/microsoft/hcsshim/unpreparelayer.go b/vendor/src/github.com/microsoft/hcsshim/unpreparelayer.go
index b204b5dc66..6b7ece601e 100644
--- a/vendor/src/github.com/microsoft/hcsshim/unpreparelayer.go
+++ b/vendor/src/github.com/microsoft/hcsshim/unpreparelayer.go
@@ -8,6 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// UnprepareLayer disables the filesystem filter for the read-write layer with
+// the given id.
 func UnprepareLayer(info DriverInfo, layerId string) error {
 	title := "hcsshim::UnprepareLayer "
 	logrus.Debugf(title+"flavour %d layerId %s", info.Flavour, layerId)