docs: accurate comments

Author: alarso16

libevm/stateconf/conf.go

@@ -23,6 +23,8 @@ import (
 
 // A StateDBCommitOption configures the behaviour of all update calls within the
 // state.StateDB.Commit() implementations.
+// This is provided in two distinct types to allow customizability to both
+// snapshot and trie database updates, but are ignored in libevm implementations.
 type StateDBCommitOption = options.Option[stateDBCommitConfig]
 
 type stateDBCommitConfig struct {
@@ -31,24 +33,33 @@ type stateDBCommitConfig struct {
 }
 
 // WithSnapshotUpdateOpts returns a StateDBCommitOption carrying a list of
+// SnapshotUpdateOptions.
+// If the list is not of length 1, the last option in the list is used.
 func WithSnapshotUpdateOpts(opts ...SnapshotUpdateOption) StateDBCommitOption {
 	return options.Func[stateDBCommitConfig](func(c *stateDBCommitConfig) {
 		// I don't like append() because there's no way to remove options, but that's a weakly held opinion
 		c.snapshotOpts = opts
 	})
 }
 
+// ExtractSnapshotUpdateOpts returns the list of SnapshotUpdateOptions carried
+// by the provided slice of StateDBCommitOption.
 func ExtractSnapshotUpdateOpts(opts ...StateDBCommitOption) []SnapshotUpdateOption {
 	return options.As(opts...).snapshotOpts
 }
 
+// WithTrieDBUpdateOpts returns a StateDBCommitOption carrying a list of
+// TrieDBUpdateOptions. If the list is not of length 1, the last option in the
+// list is used.
 func WithTrieDBUpdateOpts(opts ...TrieDBUpdateOption) StateDBCommitOption {
 	return options.Func[stateDBCommitConfig](func(c *stateDBCommitConfig) {
 		// I don't like append() because there's no way to remove options, but that's a weakly held opinion
 		c.triedbOpts = opts
 	})
 }
 
+// ExtractTrieDBUpdateOpts returns the list of TrieDBUpdateOptions carried by
+// the provided slice of StateDBCommitOption.
 func ExtractTrieDBUpdateOpts(opts ...StateDBCommitOption) []TrieDBUpdateOption {
 	return options.As(opts...).triedbOpts
 }
@@ -78,12 +89,16 @@ func ExtractSnapshotUpdatePayload(opts ...SnapshotUpdateOption) any {
 	return options.As(opts...).payload
 }
 
+// A TrieDBUpdateOption configures the behaviour of triedb.Database.Update() implementations.
 type TrieDBUpdateOption = options.Option[triedbUpdateConfig]
 
 type triedbUpdateConfig struct {
 	payload any
 }
 
+// WithTrieDBUpdatePayload returns a TrieDBUpdateOption carrying an arbitrary
+// payload. It acts only as a carrier to exploit existing function plumbing and
+// the effect on behaviour is left to the implementation receiving it.
 func WithTrieDBUpdatePayload(p any) TrieDBUpdateOption {
 	return options.Func[triedbUpdateConfig](func(c *triedbUpdateConfig) {
 		c.payload = p