Updates documentation to follow godoc conventions

Author: BrianBland

storagedriver/factory/factory.go

@@ -7,13 +7,14 @@ import (
 	"github.com/docker/docker-registry/storagedriver/ipc"
 )
 
-// Internal mapping between storage driver names and their respective factories
+// driverFactories stores an internal mapping between storage driver names and their respective
+// factories
 var driverFactories = make(map[string]StorageDriverFactory)
 
-// Factory interface for the storagedriver.StorageDriver interface
+// StorageDriverFactory is a factory interface for creating storagedriver.StorageDriver interfaces
 // Storage drivers should call Register() with a factory to make the driver available by name
 type StorageDriverFactory interface {
-	// Creates and returns a new storagedriver.StorageDriver with the given parameters
+	// Create returns a new storagedriver.StorageDriver with the given parameters
 	// Parameters will vary by driver and may be ignored
 	// Each parameter key must only consist of lowercase letters and numbers
 	Create(parameters map[string]string) (storagedriver.StorageDriver, error)
@@ -54,7 +55,7 @@ func Create(name string, parameters map[string]string) (storagedriver.StorageDri
 	return driverFactory.Create(parameters)
 }
 
-// Error returned when attempting to construct an unregistered storage driver
+// InvalidStorageDriverError records an attempt to construct an unregistered storage driver
 type InvalidStorageDriverError struct {
 	Name string
 }

storagedriver/filesystem/filesystem.go

@@ -18,20 +18,20 @@ func init() {
 	factory.Register(DriverName, &filesystemDriverFactory{})
 }
 
-// Implements the factory.StorageDriverFactory interface
+// filesystemDriverFactory implements the factory.StorageDriverFactory interface
 type filesystemDriverFactory struct{}
 
 func (factory *filesystemDriverFactory) Create(parameters map[string]string) (storagedriver.StorageDriver, error) {
 	return FromParameters(parameters), nil
 }
 
-// Storage Driver backed by a local filesystem
+// FilesystemDriver is a storagedriver.StorageDriver implementation backed by a local filesystem
 // All provided paths will be subpaths of the RootDirectory
 type FilesystemDriver struct {
 	rootDirectory string
 }
 
-// Constructs a new FilesystemDriver with a given parameters map
+// FromParameters constructs a new FilesystemDriver with a given parameters map
 // Optional Parameters:
 // - rootdirectory
 func FromParameters(parameters map[string]string) *FilesystemDriver {
@@ -45,11 +45,12 @@ func FromParameters(parameters map[string]string) *FilesystemDriver {
 	return New(rootDirectory)
 }
 
-// Constructs a new FilesystemDriver with a given rootDirectory
+// New constructs a new FilesystemDriver with a given rootDirectory
 func New(rootDirectory string) *FilesystemDriver {
 	return &FilesystemDriver{rootDirectory}
 }
 
+// subPath returns the absolute path of a key within the FilesystemDriver's storage
 func (d *FilesystemDriver) subPath(subPath string) string {
 	return path.Join(d.rootDirectory, subPath)
 }

storagedriver/inmemory/inmemory.go

@@ -19,25 +19,27 @@ func init() {
 	factory.Register(DriverName, &inMemoryDriverFactory{})
 }
 
-// Implements the factory.StorageDriverFactory interface
+// inMemoryDriverFacotry implements the factory.StorageDriverFactory interface
 type inMemoryDriverFactory struct{}
 
 func (factory *inMemoryDriverFactory) Create(parameters map[string]string) (storagedriver.StorageDriver, error) {
 	return New(), nil
 }
 
-// InMemory Storage Driver backed by a map
+// InMemoryDriver is a storagedriver.StorageDriver implementation backed by a local map
 // Intended solely for example and testing purposes
 type InMemoryDriver struct {
 	storage map[string][]byte
 	mutex   sync.RWMutex
 }
 
-// Constructs a new InMemoryDriver
+// New constructs a new InMemoryDriver
 func New() *InMemoryDriver {
 	return &InMemoryDriver{storage: make(map[string][]byte)}
 }
 
+// Implement the storagedriver.StorageDriver interface
+
 func (d *InMemoryDriver) GetContent(path string) ([]byte, error) {
 	d.mutex.RLock()
 	defer d.mutex.RUnlock()

storagedriver/ipc/client.go

@@ -15,16 +15,18 @@ import (
 	"github.com/docker/libchan/spdy"
 )
 
-// Storage Driver implementation using a managed child process communicating over IPC
+// StorageDriverClient is a storagedriver.StorageDriver implementation using a managed child process
+// communicating over IPC using libchan with a unix domain socket
 type StorageDriverClient struct {
 	subprocess *exec.Cmd
 	socket     *os.File
 	transport  *spdy.Transport
 	sender     libchan.Sender
 }
 
-// Constructs a new out-of-process storage driver using the driver name and configuration parameters
-// Must call Start() on this driver client before remote method calls can be made
+// NewDriverClient constructs a new out-of-process storage driver using the driver name and
+// configuration parameters
+// A user must call Start on this driver client before remote method calls can be made
 //
 // Looks for drivers in the following locations in order:
 // - Storage drivers directory (to be determined, yet not implemented)
@@ -54,7 +56,8 @@ func NewDriverClient(name string, parameters map[string]string) (*StorageDriverC
 	}, nil
 }
 
-// Starts the designated child process storage driver and binds a socket to this process for IPC
+// Start starts the designated child process storage driver and binds a socket to this process for
+// IPC method calls
 func (driver *StorageDriverClient) Start() error {
 	fileDescriptors, err := syscall.Socketpair(syscall.AF_LOCAL, syscall.SOCK_STREAM, 0)
 	if err != nil {
@@ -102,8 +105,8 @@ func (driver *StorageDriverClient) Start() error {
 	return nil
 }
 
-// Stops the child process storage driver
-// storagedriver.StorageDriver methods called after Stop() will fail
+// Stop stops the child process storage driver
+// storagedriver.StorageDriver methods called after Stop will fail
 func (driver *StorageDriverClient) Stop() error {
 	closeSenderErr := driver.sender.Close()
 	closeTransportErr := driver.transport.Close()

storagedriver/ipc/ipc.go

@@ -10,16 +10,17 @@ import (
 	"github.com/docker/libchan"
 )
 
-// Defines a remote method call request
+// Request defines a remote method call request
 // A return value struct is to be sent over the ResponseChannel
 type Request struct {
 	Type            string
 	Parameters      map[string]interface{}
 	ResponseChannel libchan.Sender
 }
 
-// A simple wrapper around an io.ReadCloser that implements the io.ReadWriteCloser interface
-// Writes are disallowed and will return an error if ever called
+// noWriteReadWriteCloser is a simple wrapper around an io.ReadCloser that implements the
+// io.ReadWriteCloser interface
+// Calls to Write are disallowed and will return an error
 type noWriteReadWriteCloser struct {
 	io.ReadCloser
 }
@@ -28,7 +29,7 @@ func (r noWriteReadWriteCloser) Write(p []byte) (n int, err error) {
 	return 0, errors.New("Write unsupported")
 }
 
-// Wraps an io.Reader as an io.ReadWriteCloser with a nop Close and unsupported Write method
+// WrapReader wraps an io.Reader as an io.ReadWriteCloser with a nop Close and unsupported Write
 // Has no effect when an io.ReadWriteCloser is passed in
 func WrapReader(reader io.Reader) io.ReadWriteCloser {
 	if readWriteCloser, ok := reader.(io.ReadWriteCloser); ok {
@@ -45,7 +46,7 @@ type responseError struct {
 	Message string
 }
 
-// Wraps an error in a serializable struct containing the error's type and message
+// ResponseError wraps an error in a serializable struct containing the error's type and message
 func ResponseError(err error) *responseError {
 	if err == nil {
 		return nil
@@ -62,35 +63,35 @@ func (err *responseError) Error() string {
 
 // IPC method call response object definitions
 
-// Response for a ReadStream request
+// ReadStreamResponse is a response for a ReadStream request
 type ReadStreamResponse struct {
 	Reader io.ReadWriteCloser
 	Error  *responseError
 }
 
-// Response for a WriteStream request
+// WriteStreamResponse is a response for a WriteStream request
 type WriteStreamResponse struct {
 	Error *responseError
 }
 
-// Response for a ResumeWritePosition request
+// ResumeWritePositionResponse is a response for a ResumeWritePosition request
 type ResumeWritePositionResponse struct {
 	Position uint64
 	Error    *responseError
 }
 
-// Response for a List request
+// ListResponse is a response for a List request
 type ListResponse struct {
 	Keys  []string
 	Error *responseError
 }
 
-// Response for a Move request
+// MoveResponse is a response for a Move request
 type MoveResponse struct {
 	Error *responseError
 }
 
-// Response for a Delete request
+// DeleteResponse is a response for a Delete request
 type DeleteResponse struct {
 	Error *responseError
 }

storagedriver/ipc/server.go

@@ -13,10 +13,13 @@ import (
 	"github.com/docker/libchan/spdy"
 )
 
-// Construct a new IPC server handling requests for the given storagedriver.StorageDriver
-// This explicitly uses file descriptor 3 for IPC communication, as storage drivers are spawned in client.go
+// StorageDriverServer runs a new IPC server handling requests for the given
+// storagedriver.StorageDriver
+// This explicitly uses file descriptor 3 for IPC communication, as storage drivers are spawned in
+// client.go
 //
-// To create a new out-of-process driver, create a main package which calls StorageDriverServer with a storagedriver.StorageDriver
+// To create a new out-of-process driver, create a main package which calls StorageDriverServer with
+// a storagedriver.StorageDriver
 func StorageDriverServer(driver storagedriver.StorageDriver) error {
 	childSocket := os.NewFile(3, "childSocket")
 	defer childSocket.Close()
@@ -39,9 +42,10 @@ func StorageDriverServer(driver storagedriver.StorageDriver) error {
 	}
 }
 
-// Receives new storagedriver.StorageDriver method requests and creates a new goroutine to handle each request
-//
-// Requests are expected to be of type ipc.Request as the parameters are unknown until the request type is deserialized
+// receive receives new storagedriver.StorageDriver method requests and creates a new goroutine to
+// handle each request
+// Requests are expected to be of type ipc.Request as the parameters are unknown until the request
+// type is deserialized
 func receive(driver storagedriver.StorageDriver, receiver libchan.Receiver) {
 	for {
 		var request Request
@@ -53,7 +57,7 @@ func receive(driver storagedriver.StorageDriver, receiver libchan.Receiver) {
 	}
 }
 
-// Handles storagedriver.StorageDriver method requests as defined in client.go
+// handleRequest handles storagedriver.StorageDriver method requests as defined in client.go
 // Responds to requests using the Request.ResponseChannel
 func handleRequest(driver storagedriver.StorageDriver, request Request) {
 	switch request.Type {

storagedriver/s3/s3.go

@@ -15,32 +15,33 @@ import (
 
 const DriverName = "s3"
 
-// Chunks need to be at least 5MB to store with a multipart upload on S3
+// minChunkSize defines the minimum multipart upload chunk size
+// S3 API requires multipart upload chunks to be at least 5MB
 const minChunkSize = uint64(5 * 1024 * 1024)
 
-// The largest amount of parts you can request from S3
+// listPartsMax is the largest amount of parts you can request from S3
 const listPartsMax = 1000
 
 func init() {
 	factory.Register(DriverName, &s3DriverFactory{})
 }
 
-// Implements the factory.StorageDriverFactory interface
+// s3DriverFactory implements the factory.StorageDriverFactory interface
 type s3DriverFactory struct{}
 
 func (factory *s3DriverFactory) Create(parameters map[string]string) (storagedriver.StorageDriver, error) {
 	return FromParameters(parameters)
 }
 
-// Storage Driver backed by Amazon S3
+// S3Driver is a storagedriver.StorageDriver implementation backed by Amazon S3
 // Objects are stored at absolute keys in the provided bucket
 type S3Driver struct {
 	S3      *s3.S3
 	Bucket  *s3.Bucket
 	Encrypt bool
 }
 
-// Constructs a new S3Driver with a given parameters map
+// FromParameters constructs a new S3Driver with a given parameters map
 // Required parameters:
 // - accesskey
 // - secretkey
@@ -84,7 +85,8 @@ func FromParameters(parameters map[string]string) (*S3Driver, error) {
 	return New(accessKey, secretKey, region, encryptBool, bucket)
 }
 
-// Constructs a new S3Driver with the given AWS credentials, region, encryption flag, and bucketName
+// New constructs a new S3Driver with the given AWS credentials, region, encryption flag, and
+// bucketName
 func New(accessKey string, secretKey string, region aws.Region, encrypt bool, bucketName string) (*S3Driver, error) {
 	auth := aws.Auth{AccessKey: accessKey, SecretKey: secretKey}
 	s3obj := s3.New(auth, region)
@@ -100,6 +102,8 @@ func New(accessKey string, secretKey string, region aws.Region, encrypt bool, bu
 	return &S3Driver{s3obj, bucket, encrypt}, nil
 }
 
+// Implement the storagedriver.StorageDriver interface
+
 func (d *S3Driver) GetContent(path string) ([]byte, error) {
 	return d.Bucket.Get(path)
 }

storagedriver/storagedriver.go

@@ -5,41 +5,45 @@ import (
 	"io"
 )
 
-// Defines methods that a Storage Driver must implement for a filesystem-like key/value object storage
+// StorageDriver defines methods that a Storage Driver must implement for a filesystem-like
+// key/value object storage
 type StorageDriver interface {
-	// Retrieve the content stored at "path" as a []byte
+	// GetContent retrieves the content stored at "path" as a []byte
 	// Should primarily be used for small objects
 	GetContent(path string) ([]byte, error)
 
-	// Store the []byte content at a location designated by "path"
+	// PutContent stores the []byte content at a location designated by "path"
 	// Should primarily be used for small objects
 	PutContent(path string, content []byte) error
 
-	// Retrieve an io.ReadCloser for the content stored at "path" with a given byte offset
+	// ReadStream retrieves an io.ReadCloser for the content stored at "path" with a given byte
+	// offset
 	// May be used to resume reading a stream by providing a nonzero offset
 	ReadStream(path string, offset uint64) (io.ReadCloser, error)
 
-	// Store the contents of the provided io.ReadCloser at a location designated by "path"
+	// WriteStream stores the contents of the provided io.ReadCloser at a location designated by
+	// the given path
 	// The driver will know it has received the full contents when it has read "size" bytes
 	// May be used to resume writing a stream by providing a nonzero offset
 	// The offset must be no larger than the number of bytes already written to this path
 	WriteStream(path string, offset, size uint64, readCloser io.ReadCloser) error
 
-	// Retrieve the byte offset at which it is safe to continue writing at "path"
+	// ResumeWritePosition retrieves the byte offset at which it is safe to continue writing at the
+	// given path
 	ResumeWritePosition(path string) (uint64, error)
 
-	// Recursively lists the objects stored at a subpath of the given prefix
+	// List recursively lists the objects stored at a subpath of the given prefix
 	List(prefix string) ([]string, error)
 
-	// Moves an object stored at sourcePath to destPath, removing the original object
+	// Move moves an object stored at sourcePath to destPath, removing the original object
 	// Note: This may be no more efficient than a copy followed by a delete for many implementations
 	Move(sourcePath string, destPath string) error
 
-	// Recursively deletes all objects stored at "path" and its subpaths
+	// Delete recursively deletes all objects stored at "path" and its subpaths
 	Delete(path string) error
 }
 
-// Error returned when operating on a nonexistent path
+// PathNotFoundError is returned when operating on a nonexistent path
 type PathNotFoundError struct {
 	Path string
 }
@@ -48,7 +52,7 @@ func (err PathNotFoundError) Error() string {
 	return fmt.Sprintf("Path not found: %s", err.Path)
 }
 
-// Error returned when attempting to read or write from an invalid offset
+// InvalidOffsetError is returned when attempting to read or write from an invalid offset
 type InvalidOffsetError struct {
 	Path   string
 	Offset uint64