Update documentation to storage package

Signed-off-by: Derek McGowan <derek@mcgstyle.net>

snapshot/storage/bolt.go

@@ -16,6 +16,10 @@ var (
 	bucketKeyStorageVersion = []byte("v1")
 	bucketKeySnapshot       = []byte("snapshots")
 	bucketKeyParents        = []byte("parents")
+
+	// ErrNoTransaction is returned when an operation is attempted with
+	// a context which is not inside of a transaction.
+	ErrNoTransaction = errors.New("no transaction in context")
 )
 
 type boltFileTransactor struct {
@@ -301,7 +305,7 @@ func CommitActive(ctx context.Context, key, name string) (id string, err error)
 func withBucket(ctx context.Context, fn func(context.Context, *bolt.Bucket, *bolt.Bucket) error) error {
 	t, ok := ctx.Value(transactionKey{}).(*boltFileTransactor)
 	if !ok {
-		return errors.Errorf("no transaction in context")
+		return ErrNoTransaction
 	}
 	bkt := t.tx.Bucket(bucketKeyStorageVersion)
 	if bkt == nil {
@@ -313,7 +317,7 @@ func withBucket(ctx context.Context, fn func(context.Context, *bolt.Bucket, *bol
 func createBucketIfNotExists(ctx context.Context, fn func(context.Context, *bolt.Bucket, *bolt.Bucket) error) error {
 	t, ok := ctx.Value(transactionKey{}).(*boltFileTransactor)
 	if !ok {
-		return errors.Errorf("no transaction in context")
+		return ErrNoTransaction
 	}
 
 	bkt, err := t.tx.CreateBucketIfNotExists(bucketKeyStorageVersion)

snapshot/storage/metastore.go

@@ -1,3 +1,8 @@
+// Package storage provides a metadata storage implementation for snapshot
+// drivers. Drive implementations are responsible for starting and managing
+// transactions using the defined context creator. This storage package uses
+// BoltDB for storing metadata. Access to the raw boltdb transaction is not
+// provided, but the stored object is provided by the proto subpackage.
 package storage
 
 import (
@@ -9,10 +14,15 @@ import (
 
 // Transactor is used to finalize an active transaction.
 type Transactor interface {
-	// Commit commits any changes made during the transaction.
+	// Commit commits any changes made during the transaction. On error a
+	// caller is expected to clean up any resources which would have relied
+	// on data mutated as part of this transaction. Only writable
+	// transactions can commit, non-writable must call Rollback.
 	Commit() error
 
-	// Rollback rolls back any changes made during the transaction.
+	// Rollback rolls back any changes made during the transaction. This
+	// must be called on all non-writable transactions and aborted writable
+	// transaction.
 	Rollback() error
 }
 
@@ -48,7 +58,8 @@ func NewMetaStore(dbfile string) (*MetaStore, error) {
 
 type transactionKey struct{}
 
-// TransactionContext creates a new transaction context.
+// TransactionContext creates a new transaction context. The writable value
+// should be set to true for transactions which are expected to mutate data.
 func (ms *MetaStore) TransactionContext(ctx context.Context, writable bool) (context.Context, Transactor, error) {
 	db, err := bolt.Open(ms.dbfile, 0600, nil)
 	if err != nil {