kv, db: fix fmt and comments

db/db.go

@@ -10,7 +10,8 @@ var ErrKeyNotFound = errors.New("key not found")
 // ErrEmptyKey is returned when key is empty.
 var ErrEmptyKey = errors.New("key cannot be empty")
 
-// ErrIndexOutOfRange is returned when the iterator index is not in a valid range.
+// ErrIndexOutOfRange is returned when the iterator index is not in a valid
+// range.
 var ErrIndexOutOfRange = errors.New("iterator index out of range")
 
 // Codec can do encoding/decoding between arbitrary data object and bytes.
@@ -20,37 +21,37 @@ type Codec interface {
 	Encode(obj interface{}) ([]byte, error)
 
 	// Decode the bytes to its original data object and assign it to the given
-	// variable. Value underlying `value` must be a pointer to the correct
-	// type for object.
+	// variable. Value underlying `value` must be a pointer to the correct type
+	// for object.
 	Decode(data []byte, value interface{}) error
 }
 
-// DB is a key-value database which requires the key to be a string and the value
-// can be encoded/decoded by the codec. It allows user to maintain multiple tables
-// with the same underlying database driver.
+// DB is a key-value database which requires the key to be a string and the
+// value can be encoded/decoded by the codec. It allows user to maintain
+// multiple tables with the same underlying database driver.
 type DB interface {
 
-	// Close will close the DB.
+	// Close the DB and free all of its resources. The DB must not be used after
+	// being closed.
 	Close() error
 
-	// Insert the key-value pair into the table with given name. It will
-	// return `ErrEmptyKey` if the key is empty.
+	// Insert writes the key-value into the DB.
 	Insert(key string, value interface{}) error
 
-	// Get retrieves the value of given key from the specified table and unmarshals
-	// it to the given variable. Value underlying `value` must be a pointer to
-	// the correct type for object. It will return ErrTableNotFound if the table
-	// doesn't exist. It will return `ErrEmptyKey` if the key is empty. It will
-	// return `ErrKeyNotFound` if there's no value associated with the key.
+	// Get the value associated with the given key and write it to the value
+	// interface. The value interface must be a pointer. If the key cannot be
+	// found, then ErrKeyNotFound is returned.
 	Get(key string, value interface{}) error
 
-	// Delete the data entry with given key from the specified table.
+	// Delete the value with the given key from the DB.
 	Delete(key string) error
 
-	// Size returns the number of data entries in the given table.
+	// Size returns the number of key/value pairs in the DB where the key begins
+	// with the given prefix.
 	Size(prefix string) (int, error)
 
-	// Iterator returns a iterator of the table with given name.
+	// Iterator over the key/value pairs in the DB where the key begins with the
+	// given prefix.
 	Iterator(prefix string) Iterator
 }
 
@@ -62,11 +63,12 @@ type Iterator interface {
 	// return false.
 	Next() bool
 
-	// Key of the current key-value tuple. Calling Key() without calling
-	// Next() or when no next item in the iter may result in `ErrIndexOutOfRange`
+	// Key of the current key-value tuple. Calling Key() without calling Next()
+	// or when no next item in the iter may result in `ErrIndexOutOfRange`
 	Key() (string, error)
 
 	// Value of the current key-value tuple. Calling Value() without calling
-	// Next() or when no next item in the iter will result in `ErrIndexOutOfRange`
+	// Next() or when no next item in the iter will result in
+	// `ErrIndexOutOfRange`
 	Value(value interface{}) error
 }

db/table.go

@@ -6,26 +6,26 @@ import (
 	"golang.org/x/crypto/sha3"
 )
 
-// Table is an abstraction over the DB that enforces a particular type of
-// pattern in the key (i.e. same key prefix). It requires the key to be a
-// non-empty string and the value can be encoded/decoded by the used Codec.
+// A Table is an abstraction over the DB that partitions key/value pairs. The
+// Table name must be unique compared to other Table names. The key/value pairs
+// are encoded and decoded using the Codec of the underlying DB.
 type Table interface {
 
-	// Insert writes the key-value into the table.
+	// Insert writes the key-value into the Table.
 	Insert(key string, value interface{}) error
 
-	// Get the value associated with the given key and assign it to the given
-	// variable. This function returns ErrKeyNotFound if the key cannot be found.
+	// Get the value associated with the given key and write it to the value
+	// interface. The value interface must be a pointer. If the key cannot be
+	// found, then ErrKeyNotFound is returned.
 	Get(key string, value interface{}) error
 
-	// Delete the value with the given key from the table. It is safe to use
-	// this function to delete a key which is not in the table.
+	// Delete the value with the given key from the Table.
 	Delete(key string) error
 
-	// Size returns the number of data entries in the table.
+	// Size returns the number of key/value pairs in the Table.
 	Size() (int, error)
 
-	// Iterator returns an iterator that can iterate over table.
+	// Iterator over the key/value pairs in the Table.
 	Iterator() Iterator
 }
 
@@ -34,7 +34,8 @@ type table struct {
 	nameHash string
 }
 
-// NewTable creates a new table given name basing on provided DB.
+// NewTable creates a new Table with the given name. If the underlying DB is
+// safe for concurrent use, then the Table is safe for concurrent use.
 func NewTable(db DB, name string) Table {
 	hash := sha3.Sum256([]byte(name))
 	return &table{
@@ -43,32 +44,26 @@ func NewTable(db DB, name string) Table {
 	}
 }
 
-// Insert implements the Table interface.
 func (t *table) Insert(key string, value interface{}) error {
 	return t.db.Insert(t.keyWithPrefix(key), value)
 }
 
-// Get implements the Table interface.
 func (t *table) Get(key string, value interface{}) error {
 	return t.db.Get(t.keyWithPrefix(key), value)
 }
 
-// Delete implements the Table interface.
 func (t *table) Delete(key string) error {
 	return t.db.Delete(t.keyWithPrefix(key))
 }
 
-// Size implements the Table interface.
 func (t *table) Size() (int, error) {
 	return t.db.Size(t.keyWithPrefix(""))
 }
 
-// Iterator implements the Table interface.
 func (t *table) Iterator() Iterator {
 	return t.db.Iterator(t.keyWithPrefix(""))
 }
 
-// keyWithPrefix formats the key with table hash.
 func (t *table) keyWithPrefix(key string) string {
 	return fmt.Sprintf("%v_%v", t.nameHash, key)
 }

kv.go

@@ -1,6 +1,6 @@
-// Package kv defines a standard interface for key-value stores and key-value
-// iterators. It provides persistent implementations using BadgerDB. It provides
-// non-persistent implementations using a concurrent-safe in-memory map.
+// Package kv defines a standard interface for key-value storage and iteration.
+// It supports persistent storage using LevelDB and BadgerDB. It also supports
+// non-persistent storage using concurrent-safe in-memory maps.
 package kv
 
 import (
@@ -19,32 +19,27 @@ var (
 	// ErrKeyNotFound is returned when there is no value associated with a key.
 	ErrKeyNotFound = errors.New("key not found")
 
-	// ErrEmptyKey is returned when key is empty.
+	// ErrEmptyKey is returned when a key is the empty string.
 	ErrEmptyKey = errors.New("key cannot be empty")
 
-	// ErrIndexOutOfRange is returned when the iterator index is not in a valid range.
+	// ErrIndexOutOfRange is returned when the iterator index is less than zero,
+	// or, greater than or equal to the size of the iterator.
 	ErrIndexOutOfRange = errors.New("iterator index out of range")
-
-	// ErrTableAlreadyExists is returned when the table with given name is already exists in the db.
-	ErrTableAlreadyExists = errors.New("table already exists")
-
-	// ErrTableNotFound is returned when there is no table with given name.
-	ErrTableNotFound = errors.New("table not found")
 )
 
 type (
-	// Table is an abstraction over the DB that enforces a particular type of
-	// pattern in the key (i.e. same key prefix). It requires the key to be a
-	// non-empty string and the value can be encoded/decoded by the used Codec.
+	// A Table is an abstraction over the DB that partitions key/value pairs. The
+	// Table name must be unique compared to other Table names.
 	Table = db.Table
 
-	// DB is able to add new table and does operations on certain table by its name.
+	// A DB is a low-level interface for storing and iterating over key/value
+	// pairs.
 	DB = db.DB
 
-	// Codec can encode and decode between arbitrary data object and bytes.
+	// A Codec defines an encoding/decoding between values and bytes.
 	Codec = db.Codec
 
-	// Iterator is used to iterate through the data in the store.
+	// An Iterator is used to lazily iterate over key/value pairs.
 	Iterator = db.Iterator
 )
 
@@ -60,7 +55,6 @@ var (
 	GobCodec = codec.GobCodec
 )
 
-// Initializing DB and table
 var (
 	// NewMemDB returns a key-value database that is implemented in-memory. This
 	// implementation is fast, but does not store data on-disk. It is safe for
@@ -79,7 +73,6 @@ var (
 	NewTable = db.NewTable
 )
 
-// Table wrappers
 var (
 	// NewLRUTable wraps a given Table and creates a Table which has lru cache.
 	NewLRUTable = lru.NewLruTable