all: fix documentation
diff --git a/leveldb/batch.go b/leveldb/batch.go
index 548f25d..2259200 100644
--- a/leveldb/batch.go
+++ b/leveldb/batch.go
@@ -16,7 +16,8 @@
"github.com/syndtr/goleveldb/leveldb/storage"
)
-// ErrBatchCorrupted records reason of batch corruption.
+// ErrBatchCorrupted records reason of batch corruption. This error will be
+// wrapped with errors.ErrCorrupted.
type ErrBatchCorrupted struct {
Reason string
}
diff --git a/leveldb/cache/cache.go b/leveldb/cache/cache.go
index f28e1bd..c5940b2 100644
--- a/leveldb/cache/cache.go
+++ b/leveldb/cache/cache.go
@@ -16,7 +16,7 @@
)
// Cacher provides interface to implements a caching functionality.
-// An implementation must be goroutine-safe.
+// An implementation must be safe for concurrent use.
type Cacher interface {
// Capacity returns cache capacity.
Capacity() int
diff --git a/leveldb/db.go b/leveldb/db.go
index a8a4395..a02cb2c 100644
--- a/leveldb/db.go
+++ b/leveldb/db.go
@@ -160,10 +160,10 @@
// os.ErrExist error.
//
// Open will return an error with type of ErrCorrupted if corruption
-// detected in the DB. Corrupted DB can be recovered with Recover
-// function.
+// detected in the DB. Use errors.IsCorrupted to test whether an error is
+// due to corruption. Corrupted DB can be recovered with Recover function.
//
-// The returned DB instance is goroutine-safe.
+// The returned DB instance is safe for concurrent use.
// The DB must be closed after use, by calling Close method.
func Open(stor storage.Storage, o *opt.Options) (db *DB, err error) {
s, err := newSession(stor, o)
@@ -200,13 +200,13 @@
// os.ErrExist error.
//
// OpenFile uses standard file-system backed storage implementation as
-// desribed in the leveldb/storage package.
+// described in the leveldb/storage package.
//
// OpenFile will return an error with type of ErrCorrupted if corruption
-// detected in the DB. Corrupted DB can be recovered with Recover
-// function.
+// detected in the DB. Use errors.IsCorrupted to test whether an error is
+// due to corruption. Corrupted DB can be recovered with Recover function.
//
-// The returned DB instance is goroutine-safe.
+// The returned DB instance is safe for concurrent use.
// The DB must be closed after use, by calling Close method.
func OpenFile(path string, o *opt.Options) (db *DB, err error) {
stor, err := storage.OpenFile(path, o.GetReadOnly())
@@ -227,7 +227,7 @@
// The DB must already exist or it will returns an error.
// Also, Recover will ignore ErrorIfMissing and ErrorIfExist options.
//
-// The returned DB instance is goroutine-safe.
+// The returned DB instance is safe for concurrent use.
// The DB must be closed after use, by calling Close method.
func Recover(stor storage.Storage, o *opt.Options) (db *DB, err error) {
s, err := newSession(stor, o)
@@ -253,10 +253,10 @@
// The DB must already exist or it will returns an error.
// Also, Recover will ignore ErrorIfMissing and ErrorIfExist options.
//
-// RecoverFile uses standard file-system backed storage implementation as desribed
+// RecoverFile uses standard file-system backed storage implementation as described
// in the leveldb/storage package.
//
-// The returned DB instance is goroutine-safe.
+// The returned DB instance is safe for concurrent use.
// The DB must be closed after use, by calling Close method.
func RecoverFile(path string, o *opt.Options) (db *DB, err error) {
stor, err := storage.OpenFile(path, false)
@@ -858,7 +858,7 @@
// NewIterator returns an iterator for the latest snapshot of the
// underlying DB.
-// The returned iterator is not goroutine-safe, but it is safe to use
+// The returned iterator is not safe for concurrent use, but it is safe to use
// multiple iterators concurrently, with each in a dedicated goroutine.
// It is also safe to use an iterator concurrently with modifying its
// underlying DB. The resultant key/value pairs are guaranteed to be
diff --git a/leveldb/db_snapshot.go b/leveldb/db_snapshot.go
index 977f65b..2c69d2e 100644
--- a/leveldb/db_snapshot.go
+++ b/leveldb/db_snapshot.go
@@ -59,7 +59,7 @@
}
}
-// Gets minimum sequence that not being snapshoted.
+// Gets minimum sequence that not being snapshotted.
func (db *DB) minSeq() uint64 {
db.snapsMu.Lock()
defer db.snapsMu.Unlock()
@@ -131,7 +131,7 @@
}
// NewIterator returns an iterator for the snapshot of the underlying DB.
-// The returned iterator is not goroutine-safe, but it is safe to use
+// The returned iterator is not safe for concurrent use, but it is safe to use
// multiple iterators concurrently, with each in a dedicated goroutine.
// It is also safe to use an iterator concurrently with modifying its
// underlying DB. The resultant key/value pairs are guaranteed to be
diff --git a/leveldb/db_transaction.go b/leveldb/db_transaction.go
index 7aea25b..b8f7e7d 100644
--- a/leveldb/db_transaction.go
+++ b/leveldb/db_transaction.go
@@ -59,8 +59,8 @@
}
// NewIterator returns an iterator for the latest snapshot of the transaction.
-// The returned iterator is not goroutine-safe, but it is safe to use multiple
-// iterators concurrently, with each in a dedicated goroutine.
+// The returned iterator is not safe for concurrent use, but it is safe to use
+// multiple iterators concurrently, with each in a dedicated goroutine.
// It is also safe to use an iterator concurrently while writes to the
// transaction. The resultant key/value pairs are guaranteed to be consistent.
//
diff --git a/leveldb/errors.go b/leveldb/errors.go
index c8bd66a..de26498 100644
--- a/leveldb/errors.go
+++ b/leveldb/errors.go
@@ -10,6 +10,7 @@
"github.com/syndtr/goleveldb/leveldb/errors"
)
+// Common errors.
var (
ErrNotFound = errors.ErrNotFound
ErrReadOnly = errors.New("leveldb: read-only mode")
diff --git a/leveldb/iterator/iter.go b/leveldb/iterator/iter.go
index c252286..3b55532 100644
--- a/leveldb/iterator/iter.go
+++ b/leveldb/iterator/iter.go
@@ -21,13 +21,13 @@
// IteratorSeeker is the interface that wraps the 'seeks method'.
type IteratorSeeker interface {
// First moves the iterator to the first key/value pair. If the iterator
- // only contains one key/value pair then First and Last whould moves
+ // only contains one key/value pair then First and Last would moves
// to the same key/value pair.
// It returns whether such pair exist.
First() bool
// Last moves the iterator to the last key/value pair. If the iterator
- // only contains one key/value pair then First and Last whould moves
+ // only contains one key/value pair then First and Last would moves
// to the same key/value pair.
// It returns whether such pair exist.
Last() bool
@@ -48,7 +48,7 @@
Prev() bool
}
-// CommonIterator is the interface that wraps common interator methods.
+// CommonIterator is the interface that wraps common iterator methods.
type CommonIterator interface {
IteratorSeeker
@@ -71,14 +71,15 @@
// Iterator iterates over a DB's key/value pairs in key order.
//
-// When encouter an error any 'seeks method' will return false and will
+// When encounter an error any 'seeks method' will return false and will
// yield no key/value pairs. The error can be queried by calling the Error
// method. Calling Release is still necessary.
//
// An iterator must be released after use, but it is not necessary to read
// an iterator until exhaustion.
-// Also, an iterator is not necessarily goroutine-safe, but it is safe to use
-// multiple iterators concurrently, with each in a dedicated goroutine.
+// Also, an iterator is not necessarily safe for concurrent use, but it is
+// safe to use multiple iterators concurrently, with each in a dedicated
+// goroutine.
type Iterator interface {
CommonIterator
@@ -98,7 +99,7 @@
//
// ErrorCallbackSetter implemented by indexed and merged iterator.
type ErrorCallbackSetter interface {
- // SetErrorCallback allows set an error callback of the coresponding
+ // SetErrorCallback allows set an error callback of the corresponding
// iterator. Use nil to clear the callback.
SetErrorCallback(f func(err error))
}
diff --git a/leveldb/memdb/memdb.go b/leveldb/memdb/memdb.go
index 1395bd9..18a19ed 100644
--- a/leveldb/memdb/memdb.go
+++ b/leveldb/memdb/memdb.go
@@ -17,6 +17,7 @@
"github.com/syndtr/goleveldb/leveldb/util"
)
+// Common errors.
var (
ErrNotFound = errors.ErrNotFound
ErrIterReleased = errors.New("leveldb/memdb: iterator released")
@@ -385,7 +386,7 @@
}
// NewIterator returns an iterator of the DB.
-// The returned iterator is not goroutine-safe, but it is safe to use
+// The returned iterator is not safe for concurrent use, but it is safe to use
// multiple iterators concurrently, with each in a dedicated goroutine.
// It is also safe to use an iterator concurrently with modifying its
// underlying DB. However, the resultant key/value pairs are not guaranteed
@@ -411,7 +412,7 @@
}
// Size returns sum of keys and values length. Note that deleted
-// key/value will not be accouted for, but it will still consume
+// key/value will not be accounted for, but it will still consume
// the buffer, since the buffer is append only.
func (p *DB) Size() int {
p.mu.RLock()
@@ -453,11 +454,14 @@
p.mu.Unlock()
}
-// New creates a new initalized in-memory key/value DB. The capacity
+// New creates a new initialized in-memory key/value DB. The capacity
// is the initial key/value buffer capacity. The capacity is advisory,
// not enforced.
//
-// The returned DB instance is goroutine-safe.
+// This DB is append-only, deleting an entry would remove entry node but not
+// reclaim KV buffer.
+//
+// The returned DB instance is safe for concurrent use.
func New(cmp comparer.BasicComparer, capacity int) *DB {
p := &DB{
cmp: cmp,
diff --git a/leveldb/session.go b/leveldb/session.go
index 769e4a0..f3e7477 100644
--- a/leveldb/session.go
+++ b/leveldb/session.go
@@ -18,7 +18,8 @@
"github.com/syndtr/goleveldb/leveldb/storage"
)
-// ErrManifestCorrupted records manifest corruption.
+// ErrManifestCorrupted records manifest corruption. This error will be
+// wrapped with errors.ErrCorrupted.
type ErrManifestCorrupted struct {
Field string
Reason string
diff --git a/leveldb/table/reader.go b/leveldb/table/reader.go
index 67de650..c5be420 100644
--- a/leveldb/table/reader.go
+++ b/leveldb/table/reader.go
@@ -26,12 +26,15 @@
"github.com/syndtr/goleveldb/leveldb/util"
)
+// Reader errors.
var (
ErrNotFound = errors.ErrNotFound
ErrReaderReleased = errors.New("leveldb/table: reader released")
ErrIterReleased = errors.New("leveldb/table: iterator released")
)
+// ErrCorrupted describes error due to corruption. This error will be wrapped
+// with errors.ErrCorrupted.
type ErrCorrupted struct {
Pos int64
Size int64
@@ -783,8 +786,8 @@
// table. And a nil Range.Limit is treated as a key after all keys in
// the table.
//
-// The returned iterator is not goroutine-safe and should be released
-// when not used.
+// The returned iterator is not safe for concurrent use and should be released
+// after use.
//
// Also read Iterator documentation of the leveldb/iterator package.
func (r *Reader) NewIterator(slice *util.Range, ro *opt.ReadOptions) iterator.Iterator {
@@ -1013,7 +1016,7 @@
// NewReader creates a new initialized table reader for the file.
// The fi, cache and bpool is optional and can be nil.
//
-// The returned table reader instance is goroutine-safe.
+// The returned table reader instance is safe for concurrent use.
func NewReader(f io.ReaderAt, size int64, fd storage.FileDesc, cache *cache.NamespaceGetter, bpool *util.BufferPool, o *opt.Options) (*Reader, error) {
if f == nil {
return nil, errors.New("leveldb/table: nil file")
diff --git a/leveldb/table/writer.go b/leveldb/table/writer.go
index 274dee6..b96b271 100644
--- a/leveldb/table/writer.go
+++ b/leveldb/table/writer.go
@@ -349,7 +349,7 @@
// NewWriter creates a new initialized table writer for the file.
//
-// Table writer is not goroutine-safe.
+// Table writer is not safe for concurrent use.
func NewWriter(f io.Writer, o *opt.Options) *Writer {
w := &Writer{
writer: f,
