merkledb -- nits

x/merkledb/batch.go

@@ -7,15 +7,12 @@ import "github.com/ava-labs/avalanchego/database"
 
 var _ database.Batch = (*batch)(nil)
 
-// batch is a write-only database that commits changes to its host database
-// when Write is called.
 type batch struct {
 	database.BatchOps
 
 	db *merkleDB
 }
 
-// apply all operations in order to the database and write the result to disk
 func (b *batch) Write() error {
 	return b.db.commitBatch(b.Ops)
 }

x/merkledb/cache.go

@@ -12,9 +12,11 @@ import (
 
 // A cache that calls [onEviction] on the evicted element.
 type onEvictCache[K comparable, V any] struct {
-	lock       sync.RWMutex
-	maxSize    int
-	fifo       linkedhashmap.LinkedHashmap[K, V]
+	lock    sync.RWMutex
+	maxSize int
+	fifo    linkedhashmap.LinkedHashmap[K, V]
+	// Must not call any method that grabs [c.lock]
+	// because this would cause a deadlock.
 	onEviction func(V) error
 }
 
@@ -27,6 +29,7 @@ func newOnEvictCache[K comparable, V any](maxSize int, onEviction func(V) error)
 }
 
 // removeOldest returns and removes the oldest element from this cache.
+// Assumes [c.lock] is held.
 func (c *onEvictCache[K, V]) removeOldest() (K, V, bool) {
 	k, v, exists := c.fifo.Oldest()
 	if exists {

x/merkledb/db.go

@@ -76,11 +76,8 @@ type ChangeProofer interface {
 	//     If [end] is nothing, all keys are considered < [end].
 	//   - [proof.KeyValues] and [proof.DeletedKeys] are sorted in order of increasing key.
 	//   - [proof.StartProof] and [proof.EndProof] are well-formed.
-	//   - When the keys in [proof.KeyValues] are added to [db] and the keys in [proof.DeletedKeys]
-	//     are removed from [db], the root ID of [db] is [expectedEndRootID].
-	//
-	// This is defined on Database instead of ChangeProof because it accesses
-	// database internals.
+	//   - When the changes in [proof.KeyChanes] are applied,
+	//     the root ID of the database is [expectedEndRootID].
 	VerifyChangeProof(
 		ctx context.Context,
 		proof *ChangeProof,
@@ -146,6 +143,7 @@ type merkleDB struct {
 	// Should be held before taking [db.lock]
 	commitLock sync.RWMutex
 
+	// Stores this trie's nodes.
 	nodeDB database.Database
 
 	// Stores data about the database's current state.
@@ -155,7 +153,8 @@ type merkleDB struct {
 	// Note that a call to Put may cause a node to be evicted
 	// from the cache, which will call [OnEviction].
 	// A non-nil error returned from Put is considered fatal.
-	nodeCache         onEvictCache[path, *node]
+	nodeCache onEvictCache[path, *node]
+	// Stores any error returned by [onEviction].
 	onEvictionErr     utils.Atomic[error]
 	evictionBatchSize int
 
@@ -979,6 +978,8 @@ func (*merkleDB) CommitToDB(context.Context) error {
 	return nil
 }
 
+// This is defined on merkleDB instead of ChangeProof
+// because it accesses database internals.
 // Assumes [db.lock] isn't held.
 func (db *merkleDB) VerifyChangeProof(
 	ctx context.Context,