Doc: Add godoc to cache and metrics packages.

Refers to #40

balloon/cache/cache.go

@@ -14,6 +14,8 @@
    limitations under the License.
 */
 
+// Package cache implements the interface to interact with a cache.
+// There are 4 implemented caches: freecache, lru, passthrough, and simple cache.
 package cache
 
 import (

balloon/cache/free.go

@@ -28,12 +28,15 @@ type FreeCache struct {
 	cached *freecache.Cache
 }
 
+// NewFreeCache funtion returns a new cache with a parametrized size.
 func NewFreeCache(initialSize int) *FreeCache {
 	cache := freecache.NewCache(initialSize)
 	debug.SetGCPercent(20)
 	return &FreeCache{cached: cache}
 }
 
+// Get function returns the value of a given key in cache, and a boolean showing if
+// the key is or is not present.
 func (c FreeCache) Get(key []byte) ([]byte, bool) {
 	value, err := c.cached.Get(key)
 	if err != nil {
@@ -42,10 +45,12 @@ func (c FreeCache) Get(key []byte) ([]byte, bool) {
 	return value, true
 }
 
+// Put function adds a new key/value pair to the cache.
 func (c *FreeCache) Put(key []byte, value []byte) {
-	c.cached.Set(key, value, 0)
+	_ = c.cached.Set(key, value, 0)
 }
 
+// Fill function inserts a bulk of key/value elements into the cache.
 func (c *FreeCache) Fill(r storage.KVPairReader) (err error) {
 	defer r.Close()
 	for {
@@ -56,17 +61,21 @@ func (c *FreeCache) Fill(r storage.KVPairReader) (err error) {
 		}
 		for _, entry := range entries {
 			if entry != nil {
-				c.cached.Set(entry.Key, entry.Value, 0)
+				_ = c.cached.Set(entry.Key, entry.Value, 0)
 			}
 		}
 	}
 	return nil
 }
 
+// Size function returns the number of items currently in the cache.
 func (c FreeCache) Size() int {
 	return int(c.cached.EntryCount())
 }
 
+// Equal function checks if every element from current cache (C) exists
+// in the cache to compare (O). It does not check that every element from (O)
+// exists in current cache (C).
 func (c FreeCache) Equal(o *FreeCache) bool {
 	it := c.cached.NewIterator()
 	entry := it.Next()

balloon/cache/lru.go

@@ -13,6 +13,9 @@ type entry struct {
 	value []byte
 }
 
+// LruReadThroughCache implemets a "Last Recent Used" cache with a storage backend.
+// Therefore, "writes" are done in-memory, but "reads" are done checking the storage.
+// It uses an "evictList" for the LRU functionality.
 type LruReadThroughCache struct {
 	table     storage.Table
 	store     storage.Store
@@ -21,6 +24,7 @@ type LruReadThroughCache struct {
 	evictList *list.List
 }
 
+// NewLruReadThroughCache returns a new cacheSize cache with an asociated storage.
 func NewLruReadThroughCache(table storage.Table, store storage.Store, cacheSize uint16) *LruReadThroughCache {
 	return &LruReadThroughCache{
 		table:     table,
@@ -31,6 +35,8 @@ func NewLruReadThroughCache(table storage.Table, store storage.Store, cacheSize
 	}
 }
 
+// Get function returns the value of a given key in cache. If it is not present, it looks
+// on the storage. Finally it returns a boolean showing if the key is or is not present.
 func (c LruReadThroughCache) Get(key []byte) ([]byte, bool) {
 	var k [lruKeySize]byte
 	copy(k[:], key)
@@ -46,6 +52,8 @@ func (c LruReadThroughCache) Get(key []byte) ([]byte, bool) {
 	return e.Value.(*entry).value, ok
 }
 
+// Put function adds a new key/value element to the in-memory cache, or updates it if it
+// exists. It also updates the LRU eviction list.
 func (c *LruReadThroughCache) Put(key []byte, value []byte) {
 	var k [lruKeySize]byte
 	copy(k[:], key)
@@ -68,6 +76,7 @@ func (c *LruReadThroughCache) Put(key []byte, value []byte) {
 	}
 }
 
+// Fill function inserts a bulk of key/value elements into the cache.
 func (c *LruReadThroughCache) Fill(r storage.KVPairReader) (err error) {
 	defer r.Close()
 	for {
@@ -103,6 +112,7 @@ func (c *LruReadThroughCache) Fill(r storage.KVPairReader) (err error) {
 	return nil
 }
 
+// Size function returns the number of items currently in the cache.
 func (c *LruReadThroughCache) Size() int {
 	return c.evictList.Len()
 }

balloon/cache/passthrough.go

@@ -20,18 +20,22 @@ import (
 	"github.com/bbva/qed/storage"
 )
 
+// PassThroughCache is not a cache itself. It stores data directly on disk.
 type PassThroughCache struct {
 	table storage.Table
 	store storage.Store
 }
 
+// NewPassThroughCache initializes a cache with the given underlaying storage.
 func NewPassThroughCache(table storage.Table, store storage.Store) *PassThroughCache {
 	return &PassThroughCache{
 		table: table,
 		store: store,
 	}
 }
 
+// Get function returns the value of a given key by looking for it on storage.
+// It also returns a boolean showing if the key is or is not present.
 func (c PassThroughCache) Get(key []byte) ([]byte, bool) {
 	pair, err := c.store.Get(c.table, key)
 	if err != nil {

balloon/cache/passthrough_test.go

@@ -45,7 +45,7 @@ func TestPassThroughCache(t *testing.T) {
 	for i, c := range testCases {
 		if c.cached {
 			err := store.Mutate([]*storage.Mutation{
-				{table, c.key, c.value},
+				{Table: table, Key: c.key, Value: c.value},
 			})
 			require.NoError(t, err)
 		}

balloon/cache/simple.go

@@ -24,27 +24,33 @@ import (
 
 const keySize = 34
 
+// SimpleCache is a fixed size in-memory map of byte array as key and values.
 type SimpleCache struct {
 	cached map[[keySize]byte][]byte
 }
 
+// NewSimpleCache returns an empty SimpleCache of 'initialSize' size.
 func NewSimpleCache(initialSize uint64) *SimpleCache {
 	return &SimpleCache{make(map[[keySize]byte][]byte, initialSize)}
 }
 
+// Get function returns the value of a given key in cache, and a boolean showing if
+// the key is or is not present.
 func (c SimpleCache) Get(key []byte) ([]byte, bool) {
 	var k [keySize]byte
 	copy(k[:], key)
 	value, ok := c.cached[k]
 	return value, ok
 }
 
+// Put function adds a key/value element to the SimpleCache.
 func (c *SimpleCache) Put(key []byte, value []byte) {
 	var k [keySize]byte
 	copy(k[:], key)
 	c.cached[k] = value
 }
 
+// Fill function inserts a bulk of key/value elements into the cache.
 func (c *SimpleCache) Fill(r storage.KVPairReader) (err error) {
 	defer r.Close()
 	for {
@@ -64,10 +70,14 @@ func (c *SimpleCache) Fill(r storage.KVPairReader) (err error) {
 	return nil
 }
 
+// Size function returns the number of items currently in the cache.
 func (c SimpleCache) Size() int {
 	return len(c.cached)
 }
 
+// Equal function checks if every element from current cache (C) exists
+// in the cache to compare (O). It does not check that every element from (O)
+// exists in current cache (C).
 func (c SimpleCache) Equal(o *SimpleCache) bool {
 	for k, v1 := range c.cached {
 		v2, ok := o.cached[k]

balloon/cache/test_util.go

@@ -85,7 +85,10 @@ func NewFakeKVPairReader(numElems uint64) *FakeKVPairReader {
 
 func (r *FakeKVPairReader) Read(buffer []*storage.KVPair) (n int, err error) {
 	for n = 0; r.Remaining > 0 && n < len(buffer); n++ {
-		buffer[n] = &storage.KVPair{util.Uint64AsBytes(r.index), rand.Bytes(8)}
+		buffer[n] = &storage.KVPair{
+			Key:   util.Uint64AsBytes(r.index),
+			Value: rand.Bytes(8),
+		}
 		r.Remaining--
 		r.index++
 	}

metrics/metrics.go

@@ -14,6 +14,8 @@
    limitations under the License.
 */
 
+// Package metrics implements an HTTP metrics server along with its
+// life cycle: start, shutdown, and register metrics.
 package metrics
 
 import (