From 0f09bcd16a0ed5aa87c4ad84f033e9be3acaa138 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Fri, 18 Mar 2016 16:28:42 -0700 Subject: [PATCH 1/2] Add documentation for how to register new StorageDrivers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit adds context-specific documentation on StorageDriver, StorageDriverFactory, and the factory’s Register func, explaining how the internal registration mechanism should be used. This documentation follows from the thread starting at https://github.com/deis/builder/pull/262/files#r56720200. cc/ @stevvooe Signed-off-by: Aaron Schlesinger --- docs/storage/driver/factory/factory.go | 11 ++++++++++- docs/storage/driver/storagedriver.go | 9 ++++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/storage/driver/factory/factory.go b/docs/storage/driver/factory/factory.go index e84f0026..a9c04ec5 100644 --- a/docs/storage/driver/factory/factory.go +++ b/docs/storage/driver/factory/factory.go @@ -11,7 +11,14 @@ import ( var driverFactories = make(map[string]StorageDriverFactory) // 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 +// Storage drivers should call Register() with a factory to make the driver available by name. +// Individual StorageDriver implementations generally register with the factory via the Register +// func (below) in their init() funcs, and as such they should be imported anonymously before use. +// See below for an example of how to register and get a StorageDriver for S3 +// +// import _ "github.com/docker/distribution/registry/storage/driver/s3-aws" +// s3Driver, err = factory.Create("s3", storageParams) +// // assuming no error, s3Driver is the StorageDriver that communicates with S3 according to storageParams type StorageDriverFactory interface { // Create returns a new storagedriver.StorageDriver with the given parameters // Parameters will vary by driver and may be ignored @@ -21,6 +28,8 @@ type StorageDriverFactory interface { // Register makes a storage driver available by the provided name. // If Register is called twice with the same name or if driver factory is nil, it panics. +// Additionally, it is not concurrency safe. Most Storage Drivers call this function +// in their init() functions. See the documentation for StorageDriverFactory for more. func Register(name string, factory StorageDriverFactory) { if factory == nil { panic("Must not provide nil StorageDriverFactory") diff --git a/docs/storage/driver/storagedriver.go b/docs/storage/driver/storagedriver.go index 2ae9a67e..c27e1031 100644 --- a/docs/storage/driver/storagedriver.go +++ b/docs/storage/driver/storagedriver.go @@ -34,7 +34,14 @@ func (version Version) Minor() uint { const CurrentVersion Version = "0.1" // StorageDriver defines methods that a Storage Driver must implement for a -// filesystem-like key/value object storage. +// filesystem-like key/value object storage. Storage Drivers are automatically +// registered via an internal registration mechanism, and generally created +// via the StorageDriverFactory interface (https://godoc.org/github.com/docker/distribution/registry/storage/driver/factory). +// See below for an example of how to get a StorageDriver for S3: +// +// import _ "github.com/docker/distribution/registry/storage/driver/s3-aws" +// s3Driver, err = factory.Create("s3", storageParams) +// // assuming no error, s3Driver is the StorageDriver that communicates with S3 according to storageParams type StorageDriver interface { // Name returns the human-readable "name" of the driver, useful in error // messages and logging. By convention, this will just be the registration From 091ad89197b7b0c22e04e0aac1749e2ca4218b43 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Thu, 24 Mar 2016 09:35:04 -0700 Subject: [PATCH 2/2] Remove the example Instead, direct users to the one in the factory package Signed-off-by: Aaron Schlesinger --- docs/storage/driver/storagedriver.go | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/storage/driver/storagedriver.go b/docs/storage/driver/storagedriver.go index c27e1031..548a17d8 100644 --- a/docs/storage/driver/storagedriver.go +++ b/docs/storage/driver/storagedriver.go @@ -37,11 +37,8 @@ const CurrentVersion Version = "0.1" // filesystem-like key/value object storage. Storage Drivers are automatically // registered via an internal registration mechanism, and generally created // via the StorageDriverFactory interface (https://godoc.org/github.com/docker/distribution/registry/storage/driver/factory). -// See below for an example of how to get a StorageDriver for S3: -// -// import _ "github.com/docker/distribution/registry/storage/driver/s3-aws" -// s3Driver, err = factory.Create("s3", storageParams) -// // assuming no error, s3Driver is the StorageDriver that communicates with S3 according to storageParams +// Please see the aforementioned factory package for example code showing how to get an instance +// of a StorageDriver type StorageDriver interface { // Name returns the human-readable "name" of the driver, useful in error // messages and logging. By convention, this will just be the registration