add documentation

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Breaking Changes
 
+- [\#100](https://github.com/tendermint/tm-db/pull/100) Keys can no longer be `nil` or empty, and values can no longer be `nil` (@erikgrinaker)
+
 - [\#98](https://github.com/tendermint/tm-db/pull/98) `NewDB` now returns an error instead of panicing (@erikgrinaker)
 
 - [\#96](https://github.com/tendermint/tm-db/pull/96) `Batch.Set()`, `Delete()`, and `Close()` may now error (@erikgrinaker)

types.go

@@ -16,9 +16,8 @@ var (
 // DB is the main interface for all database backends. DBs are concurrency-safe. Callers must call
 // Close on the database when done.
 //
-// Keys and values can be empty, or nil which is interpreted as an empty byte slice. Keys and values
-// should be considered read-only, both when returned and when given, and must be copied before they
-// are modified.
+// Keys cannot be nil or empty, while values cannot be nil. Keys and values should be considered
+// read-only, both when returned and when given, and must be copied before they are modified.
 type DB interface {
 	// Get fetches the value of the given key, or nil if it does not exist.
 	// CONTRACT: key, value readonly []byte
@@ -44,14 +43,16 @@ type DB interface {
 
 	// Iterator returns an iterator over a domain of keys, in ascending order. The caller must call
 	// Close when done. End is exclusive, and start must be less than end. A nil start iterates
-	// from the first key, and a nil end iterates to the last key (inclusive).
+	// from the first key, and a nil end iterates to the last key (inclusive). Empty keys are not
+	// valid.
 	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
 	// CONTRACT: start, end readonly []byte
 	Iterator(start, end []byte) (Iterator, error)
 
 	// ReverseIterator returns an iterator over a domain of keys, in descending order. The caller
 	// must call Close when done. End is exclusive, and start must be less than end. A nil end
 	// iterates from the last key (inclusive), and a nil start iterates to the first key (inclusive).
+	// Empty keys are not valid.
 	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
 	// CONTRACT: start, end readonly []byte
 	ReverseIterator(start, end []byte) (Iterator, error)