doc: comments on all exported identifiers

Author: ARR4N

core/vm/jump_table.libevm.go

@@ -2,6 +2,7 @@ package vm
 
 import "github.com/ethereum/go-ethereum/params"
 
+// NewOperation constructs a new operation for inclusion in a [JumpTable].
 func NewOperation(
 	execute func(pc *uint64, interpreter *EVMInterpreter, callContext *ScopeContext) ([]byte, error),
 	constantGas uint64,
@@ -18,12 +19,18 @@ func NewOperation(
 	}
 }
 
+// Hooks are arbitrary configuration functions to modify default VM behaviour.
 type Hooks interface {
+	// OverrideJumpTable will only be called if
+	// [params.RulesHooks.OverrideJumpTable] returns true. This allows for
+	// recursive calling into [LookupInstructionSet].
 	OverrideJumpTable(params.Rules, *JumpTable) *JumpTable
 }
 
 var libevmHooks Hooks
 
+// RegisterHooks registers the Hooks. It is expected to be called in an `init()`
+// function and MUST NOT be called more than once.
 func RegisterHooks(h Hooks) {
 	if libevmHooks != nil {
 		panic("already registered")

params/hooks.libevm.go

@@ -27,6 +27,9 @@ type RulesHooks interface {
 	// [PrecompiledContract] is non-nil. If it returns `false` then the default
 	// precompile behaviour is honoured.
 	PrecompileOverride(common.Address) (_ libevm.PrecompiledContract, override bool)
+	// OverrideJumpTable signals that [vm.Hooks.OverrideJumpTable] MUST be used.
+	// Toggling the behaviour via [Rules] allows for recursive calling into
+	// functions that would otherwise infinitely call the override hook.
 	OverrideJumpTable() bool
 }
 
@@ -86,6 +89,8 @@ func (NOOPHooks) PrecompileOverride(common.Address) (libevm.PrecompiledContract,
 	return nil, false
 }
 
+// OverrideJumpTable returns false, leaving all JumpTables unmodified even if
+// [vm.Hooks] have been registered.
 func (NOOPHooks) OverrideJumpTable() bool {
 	return false
 }