Add documentation

sdk/handler.go

@@ -41,7 +41,8 @@ func (h *Handler) Serve(l net.Listener) error {
 	return server.Serve(l)
 }
 
-// Gracefully shuts down the http.Server serving requests
+// Shutdown gracefully shuts down the http.Server serving requests after Serve or
+// Serve{TCP,Unix,Windows} was called.
 func (h *Handler) Shutdown(c context.Context) error {
 	return h.server.Shutdown(c)
 }

sdk/tcp_listener.go

@@ -8,6 +8,12 @@ import (
 	"github.com/docker/go-connections/sockets"
 )
 
+// NewTCPListener constructs a net.Listener to use for serving requests at the given TCP address.
+// It also writes the spec file in the right directory for docker to read.
+//
+// Due to constrains for running Docker in Docker on Windows, data-root directory
+// of docker daemon must be provided. To get default directory, use
+// WindowsDefaultDaemonRootDir() function. On Unix, this parameter is ignored.
 func NewTCPListener(address, pluginName, daemonDir string, tlsConfig *tls.Config) (net.Listener, string, error) {
 	listener, err := sockets.NewTCPSocket(address, tlsConfig)
 	if err != nil {

sdk/unix_listener.go

@@ -12,6 +12,8 @@ import (
 
 const pluginSockDir = "/run/docker/plugins"
 
+// NewUnixListener constructs a net.Listener to use for serving requests at the given unix socket.
+// It also creates the socket file in the right directory for docker to read.
 func NewUnixListener(pluginName string, gid int) (net.Listener, string, error) {
 	path, err := fullSocketAddress(pluginName)
 	if err != nil {

sdk/windows_listener_unsupported.go

@@ -11,6 +11,12 @@ var (
 	errOnlySupportedOnWindows = errors.New("named pipe creation is only supported on Windows")
 )
 
+// NewWindowsListener constructs a net.Listener to use for serving requests at the given Windows named pipe.
+// It also creates the spec file in the right directory for docker to read.
+//
+// Due to constrains for running Docker in Docker on Windows, the data-root directory
+// of docker daemon must be provided. To get default directory, use
+// WindowsDefaultDaemonRootDir() function. On Unix, this parameter is ignored.
 func NewWindowsListener(address, pluginName, daemonRoot string, pipeConfig *WindowsPipeConfig) (net.Listener, string, error) {
 	return nil, "", errOnlySupportedOnWindows
 }