storage: transactional, package documentation

Signed-off-by: Máximo Cuadros <mcuadros@gmail.com>

8 files changed, 75 insertions, 21 deletions

diff --git a/storage/transactional/config.go b/storage/transactional/config.go
index fec1f28..4d8efe1 100644
--- a/storage/transactional/config.go
+++ b/storage/transactional/config.go
@@ -2,6 +2,7 @@ package transactional
 
 import "gopkg.in/src-d/go-git.v4/config"
 
+// ConfigStorage implements the storer.ConfigStorage for the transactional package.
 type ConfigStorage struct {
 	config.ConfigStorer
 	temporal config.ConfigStorer
@@ -9,10 +10,13 @@ type ConfigStorage struct {
 	set bool
 }
 
+// NewConfigStorage returns a new ConfigStorer based on a base storer and a
+// temporal storer.
 func NewConfigStorage(s, temporal config.ConfigStorer) *ConfigStorage {
 	return &ConfigStorage{ConfigStorer: s, temporal: temporal}
 }
 
+// SetConfig honors the storer.ConfigStorer interface.
 func (c *ConfigStorage) SetConfig(cfg *config.Config) error {
 	if err := c.temporal.SetConfig(cfg); err != nil {
 		return err
@@ -22,6 +26,7 @@ func (c *ConfigStorage) SetConfig(cfg *config.Config) error {
 	return nil
 }
 
+// Config honors the storer.ConfigStorer interface.
 func (c *ConfigStorage) Config() (*config.Config, error) {
 	if !c.set {
 		return c.ConfigStorer.Config()
@@ -30,6 +35,7 @@ func (c *ConfigStorage) Config() (*config.Config, error) {
 	return c.temporal.Config()
 }
 
+// Commit it copies the config from the temporal storage into the base storage.
 func (c *ConfigStorage) Commit() error {
 	if !c.set {
 		return nil
diff --git a/storage/transactional/doc.go b/storage/transactional/doc.go
new file mode 100644
index 0000000..3a68f5f
--- /dev/null
+++ b/storage/transactional/doc.go
@@ -0,0 +1,7 @@
+// Package transactional is a transactional implementation of git.Storer, it
+// demux the write and read operation of two separate storers, allowing to merge
+// content calling Storage.Commit.
+//
+// The API and functionality of this package are considered EXPERIMENTAL and is
+// not considered stable nor production ready.
+package transactional
diff --git a/storage/transactional/index.go b/storage/transactional/index.go
index 26042d6..84e0e2f 100644
--- a/storage/transactional/index.go
+++ b/storage/transactional/index.go
@@ -5,6 +5,7 @@ import (
 	"gopkg.in/src-d/go-git.v4/plumbing/storer"
 )
 
+// IndexStorage implements the storer.IndexStorage for the transactional package.
 type IndexStorage struct {
 	storer.IndexStorer
 	temporal storer.IndexStorer
@@ -12,6 +13,8 @@ type IndexStorage struct {
 	set bool
 }
 
+// NewIndexStorage returns a new IndexStorer based on a base storer and a
+// temporal storer.
 func NewIndexStorage(s, temporal storer.IndexStorer) *IndexStorage {
 	return &IndexStorage{
 		IndexStorer: s,
@@ -19,6 +22,7 @@ func NewIndexStorage(s, temporal storer.IndexStorer) *IndexStorage {
 	}
 }
 
+// SetIndex honors the storer.IndexStorer interface.
 func (s *IndexStorage) SetIndex(idx *index.Index) (err error) {
 	if err := s.temporal.SetIndex(idx); err != nil {
 		return err
@@ -28,6 +32,7 @@ func (s *IndexStorage) SetIndex(idx *index.Index) (err error) {
 	return nil
 }
 
+// Index honors the storer.IndexStorer interface.
 func (s *IndexStorage) Index() (*index.Index, error) {
 	if !s.set {
 		return s.IndexStorer.Index()
@@ -36,15 +41,16 @@ func (s *IndexStorage) Index() (*index.Index, error) {
 	return s.temporal.Index()
 }
 
-func (c *IndexStorage) Commit() error {
-	if !c.set {
+// Commit it copies the index from the temporal storage into the base storage.
+func (s *IndexStorage) Commit() error {
+	if !s.set {
 		return nil
 	}
 
-	idx, err := c.temporal.Index()
+	idx, err := s.temporal.Index()
 	if err != nil {
 		return err
 	}
 
-	return c.IndexStorer.SetIndex(idx)
+	return s.IndexStorer.SetIndex(idx)
 }
diff --git a/storage/transactional/module.go b/storage/transactional/module.go
deleted file mode 100644
index d5f5a24..0000000
--- a/storage/transactional/module.go
+++ /dev/null
@@ -1 +0,0 @@
-package transactional
diff --git a/storage/transactional/object.go b/storage/transactional/object.go
index 21490b7..beb63d6 100644
--- a/storage/transactional/object.go
+++ b/storage/transactional/object.go
@@ -5,19 +5,24 @@ import (
 	"gopkg.in/src-d/go-git.v4/plumbing/storer"
 )
 
+// ObjectStorage implements the storer.EncodedObjectStorer for the transactional package.
 type ObjectStorage struct {
 	storer.EncodedObjectStorer
 	temporal storer.EncodedObjectStorer
 }
 
-func NewObjectStorage(s, temporal storer.EncodedObjectStorer) *ObjectStorage {
-	return &ObjectStorage{EncodedObjectStorer: s, temporal: temporal}
+// NewObjectStorage returns a new EncodedObjectStorer based on a base storer and
+// a temporal storer.
+func NewObjectStorage(base, temporal storer.EncodedObjectStorer) *ObjectStorage {
+	return &ObjectStorage{EncodedObjectStorer: base, temporal: temporal}
 }
 
+// SetEncodedObject honors the storer.EncodedObjectStorer interface.
 func (o *ObjectStorage) SetEncodedObject(obj plumbing.EncodedObject) (plumbing.Hash, error) {
 	return o.temporal.SetEncodedObject(obj)
 }
 
+// HasEncodedObject honors the storer.EncodedObjectStorer interface.
 func (o *ObjectStorage) HasEncodedObject(h plumbing.Hash) error {
 	err := o.EncodedObjectStorer.HasEncodedObject(h)
 	if err == plumbing.ErrObjectNotFound {
@@ -27,6 +32,7 @@ func (o *ObjectStorage) HasEncodedObject(h plumbing.Hash) error {
 	return err
 }
 
+// EncodedObjectSize honors the storer.EncodedObjectStorer interface.
 func (o *ObjectStorage) EncodedObjectSize(h plumbing.Hash) (int64, error) {
 	sz, err := o.EncodedObjectStorer.EncodedObjectSize(h)
 	if err == plumbing.ErrObjectNotFound {
@@ -36,6 +42,7 @@ func (o *ObjectStorage) EncodedObjectSize(h plumbing.Hash) (int64, error) {
 	return sz, err
 }
 
+// EncodedObject honors the storer.EncodedObjectStorer interface.
 func (o *ObjectStorage) EncodedObject(t plumbing.ObjectType, h plumbing.Hash) (plumbing.EncodedObject, error) {
 	obj, err := o.EncodedObjectStorer.EncodedObject(t, h)
 	if err == plumbing.ErrObjectNotFound {
@@ -45,6 +52,7 @@ func (o *ObjectStorage) EncodedObject(t plumbing.ObjectType, h plumbing.Hash) (p
 	return obj, err
 }
 
+// IterEncodedObjects honors the storer.EncodedObjectStorer interface.
 func (o *ObjectStorage) IterEncodedObjects(t plumbing.ObjectType) (storer.EncodedObjectIter, error) {
 	baseIter, err := o.EncodedObjectStorer.IterEncodedObjects(t)
 	if err != nil {
@@ -62,6 +70,7 @@ func (o *ObjectStorage) IterEncodedObjects(t plumbing.ObjectType) (storer.Encode
 	}), nil
 }
 
+// Commit it copies the objects of the temporal storage into the base storage.
 func (o *ObjectStorage) Commit() error {
 	iter, err := o.temporal.IterEncodedObjects(plumbing.AnyObject)
 	if err != nil {
diff --git a/storage/transactional/reference.go b/storage/transactional/reference.go
index 2efefd2..a7be532 100644
--- a/storage/transactional/reference.go
+++ b/storage/transactional/reference.go
@@ -6,6 +6,7 @@ import (
 	"gopkg.in/src-d/go-git.v4/storage"
 )
 
+// ReferenceStorage implements the storer.ReferenceStorage for the transactional package.
 type ReferenceStorage struct {
 	storer.ReferenceStorer
 	temporal storer.ReferenceStorer
@@ -19,20 +20,24 @@ type ReferenceStorage struct {
 	packRefs bool
 }
 
-func NewReferenceStorage(s, temporal storer.ReferenceStorer) *ReferenceStorage {
+// NewReferenceStorage returns a new ReferenceStorer based on a base storer and
+// a temporal storer.
+func NewReferenceStorage(base, temporal storer.ReferenceStorer) *ReferenceStorage {
 	return &ReferenceStorage{
-		ReferenceStorer: s,
+		ReferenceStorer: base,
 		temporal:        temporal,
 
 		deleted: make(map[plumbing.ReferenceName]struct{}, 0),
 	}
 }
 
+// SetReference honors the storer.ReferenceStorer interface.
 func (r *ReferenceStorage) SetReference(ref *plumbing.Reference) error {
 	delete(r.deleted, ref.Name())
 	return r.temporal.SetReference(ref)
 }
 
+// SetReference honors the storer.ReferenceStorer interface.
 func (r *ReferenceStorage) CheckAndSetReference(ref, old *plumbing.Reference) error {
 	if old == nil {
 		return r.SetReference(ref)
@@ -54,6 +59,7 @@ func (r *ReferenceStorage) CheckAndSetReference(ref, old *plumbing.Reference) er
 	return r.SetReference(ref)
 }
 
+// Reference honors the storer.ReferenceStorer interface.
 func (r ReferenceStorage) Reference(n plumbing.ReferenceName) (*plumbing.Reference, error) {
 	if _, deleted := r.deleted[n]; deleted {
 		return nil, plumbing.ErrReferenceNotFound
@@ -67,6 +73,7 @@ func (r ReferenceStorage) Reference(n plumbing.ReferenceName) (*plumbing.Referen
 	return ref, err
 }
 
+// IterReferences honors the storer.ReferenceStorer interface.
 func (r ReferenceStorage) IterReferences() (storer.ReferenceIter, error) {
 	baseIter, err := r.ReferenceStorer.IterReferences()
 	if err != nil {
@@ -84,6 +91,7 @@ func (r ReferenceStorage) IterReferences() (storer.ReferenceIter, error) {
 	}), nil
 }
 
+// CountLooseRefs honors the storer.ReferenceStorer interface.
 func (r ReferenceStorage) CountLooseRefs() (int, error) {
 	tc, err := r.temporal.CountLooseRefs()
 	if err != nil {
@@ -98,16 +106,20 @@ func (r ReferenceStorage) CountLooseRefs() (int, error) {
 	return tc + bc, nil
 }
 
+// PackRefs honors the storer.ReferenceStorer interface.
 func (r ReferenceStorage) PackRefs() error {
 	r.packRefs = true
 	return nil
 }
 
+// RemoveReference honors the storer.ReferenceStorer interface.
 func (r ReferenceStorage) RemoveReference(n plumbing.ReferenceName) error {
 	r.deleted[n] = struct{}{}
 	return r.temporal.RemoveReference(n)
 }
 
+// Commit it copies the reference information of the temporal storage into the
+// base storage.
 func (r ReferenceStorage) Commit() error {
 	for name := range r.deleted {
 		if err := r.ReferenceStorer.RemoveReference(name); err != nil {
diff --git a/storage/transactional/shallow.go b/storage/transactional/shallow.go
index 07663d4..bedc325 100644
--- a/storage/transactional/shallow.go
+++ b/storage/transactional/shallow.go
@@ -5,22 +5,27 @@ import (
 	"gopkg.in/src-d/go-git.v4/plumbing/storer"
 )
 
+// ShallowStorage implements the storer.ShallowStorer for the transactional package.
 type ShallowStorage struct {
 	storer.ShallowStorer
 	temporal storer.ShallowStorer
 }
 
-func NewShallowStorage(s, temporal storer.ShallowStorer) *ShallowStorage {
+// NewShallowStorage returns a new ShallowStorage based on a base storer and
+// a temporal storer.
+func NewShallowStorage(base, temporal storer.ShallowStorer) *ShallowStorage {
 	return &ShallowStorage{
-		ShallowStorer: s,
+		ShallowStorer: base,
 		temporal:      temporal,
 	}
 }
 
+// SetShallow honors the storer.ShallowStorer interface.
 func (s *ShallowStorage) SetShallow(commits []plumbing.Hash) error {
 	return s.temporal.SetShallow(commits)
 }
 
+// Shallow honors the storer.ShallowStorer interface.
 func (s *ShallowStorage) Shallow() ([]plumbing.Hash, error) {
 	shallow, err := s.temporal.Shallow()
 	if err != nil {
@@ -34,6 +39,8 @@ func (s *ShallowStorage) Shallow() ([]plumbing.Hash, error) {
 	return s.ShallowStorer.Shallow()
 }
 
+// Commit it copies the shallow information of the temporal storage into the
+// base storage.
 func (s *ShallowStorage) Commit() error {
 	commits, err := s.temporal.Shallow()
 	if err != nil || len(commits) == 0 {
diff --git a/storage/transactional/storage.go b/storage/transactional/storage.go
index 6611a43..fbb3d35 100644
--- a/storage/transactional/storage.go
+++ b/storage/transactional/storage.go
@@ -4,9 +4,12 @@ import (
 	"gopkg.in/src-d/go-git.v4/storage"
 )
 
-// Storage is an implementation of git.Storer that stores data on disk in the
-// standard git format (this is, the .git directory). Zero values of this type
-// are not safe to use, see the NewStorage function below.
+// Storage is a transactional implementation of git.Storer, it demux the write
+// and read operation of two separate storers, allowing to merge content calling
+// Storage.Commit.
+//
+// The API and functionality of this package are considered EXPERIMENTAL and is
+// not considered stable nor production ready.
 type Storage struct {
 	s, temporal storage.Storer
 
@@ -17,19 +20,23 @@ type Storage struct {
 	*ConfigStorage
 }
 
-func NewStorage(s, temporal storage.Storer) *Storage {
+// NewStorage returns a new Storage based on two repositories, base is the base
+// repository where the read operations are read and temportal is were all
+// the write operations are stored.
+func NewStorage(base, temporal storage.Storer) *Storage {
 	return &Storage{
-		s:        s,
+		s:        base,
 		temporal: temporal,
 
-		ObjectStorage:    NewObjectStorage(s, temporal),
-		ReferenceStorage: NewReferenceStorage(s, temporal),
-		IndexStorage:     NewIndexStorage(s, temporal),
-		ShallowStorage:   NewShallowStorage(s, temporal),
-		ConfigStorage:    NewConfigStorage(s, temporal),
+		ObjectStorage:    NewObjectStorage(base, temporal),
+		ReferenceStorage: NewReferenceStorage(base, temporal),
+		IndexStorage:     NewIndexStorage(base, temporal),
+		ShallowStorage:   NewShallowStorage(base, temporal),
+		ConfigStorage:    NewConfigStorage(base, temporal),
 	}
 }
 
+// Module it honors the storage.ModuleStorer interface.
 func (s *Storage) Module(name string) (storage.Storer, error) {
 	base, err := s.s.Module(name)
 	if err != nil {
@@ -44,6 +51,7 @@ func (s *Storage) Module(name string) (storage.Storer, error) {
 	return NewStorage(base, temporal), nil
 }
 
+// Commit it copies the content of the temporal storage into the base storage.
 func (s *Storage) Commit() error {
 	for _, c := range []interface{ Commit() error }{
 		s.ObjectStorage,