improve godocs and adjust naming

Author: peterargue

fvm/blueprints/scheduled_callback.go

@@ -114,7 +114,7 @@ func executeCallbackTransaction(
 // callback scheduler contract and has the following signature:
 // event PendingExecution(id: UInt64, priority: UInt8, executionEffort: UInt64, fees: UFix64, callbackOwner: Address)
 func callbackArgsFromEvent(event flow.Event) ([]byte, uint64, error) {
-	cadenceId, cadenceEffort, err := CallbackDetailsFromEvent(event)
+	cadenceId, cadenceEffort, err := ParsePendingExecutionEvent(event)
 	if err != nil {
 		return nil, 0, err
 	}
@@ -134,8 +134,9 @@ func callbackArgsFromEvent(event flow.Event) ([]byte, uint64, error) {
 	return encID, uint64(effort), nil
 }
 
-// CallbackDetailsFromEvent decodes the event payload and returns the callback ID and effort.
-func CallbackDetailsFromEvent(event flow.Event) (cadence.UInt64, cadence.UInt64, error) {
+// ParsePendingExecutionEvent decodes the PendingExecution event payload and returns the scheduled
+// transaction's id and effort.
+func ParsePendingExecutionEvent(event flow.Event) (cadence.UInt64, cadence.UInt64, error) {
 	const (
 		processedCallbackIDFieldName     = "id"
 		processedCallbackEffortFieldName = "executionEffort"

fvm/blueprints/scheduled_callback_test.go

@@ -191,14 +191,14 @@ func TestIsPendingExecutionEvent(t *testing.T) {
 	assert.True(t, blueprints.IsPendingExecutionEvent(env, createValidCallbackEvent(t, 1, 100)))
 }
 
-func TestCallbackDetailsFromEvent(t *testing.T) {
+func TestParsePendingExecutionEvent(t *testing.T) {
 	t.Parallel()
 
 	expectedID := uint64(123)
 	expectedEffort := uint64(456)
 	event := createValidCallbackEvent(t, expectedID, expectedEffort)
 
-	actualID, actualEffort, err := blueprints.CallbackDetailsFromEvent(event)
+	actualID, actualEffort, err := blueprints.ParsePendingExecutionEvent(event)
 	require.NoError(t, err)
 	assert.Equal(t, expectedID, uint64(actualID))
 	assert.Equal(t, expectedEffort, uint64(actualEffort))

module/executiondatasync/testutil/fixtures.go

@@ -16,6 +16,8 @@ import (
 	"github.com/onflow/flow-go/utils/unittest/fixtures"
 )
 
+// TestFixture contains complete random data for testing BlockExecutionData related processing.
+// It also includes expected parsed data for easy assertions.
 type TestFixture struct {
 	Block           *flow.Block
 	ExecutionResult *flow.ExecutionResult

module/state_synchronization/indexer/indexer_core.go

@@ -321,7 +321,7 @@ func collectScheduledTransactions(
 	// extract the pending execution events and create a mapping from transaction ID to scheduled transaction ID
 	for i, event := range systemChunkEvents {
 		if blueprints.IsPendingExecutionEvent(fvmEnv, event) {
-			id, _, err := blueprints.CallbackDetailsFromEvent(event)
+			id, _, err := blueprints.ParsePendingExecutionEvent(event)
 			if err != nil {
 				return nil, fmt.Errorf("could not get callback details from event %d: %w", i, err)
 			}

storage/operation/scheduled_transactions.go

@@ -22,14 +22,14 @@ func RetrieveBlockIDByScheduledTransactionID(r storage.Reader, txID flow.Identif
 	return RetrieveByKey(r, MakePrefix(codeBlockIDByScheduledTransactionID, txID), blockID)
 }
 
-// BatchIndexScheduledTransactionID indexes the scheduled transaction by its scheduled transaction ID and transaction ID.
+// BatchIndexScheduledTransactionID indexes the scheduled transaction's transaction ID by its scheduled transaction ID.
 //
 // No errors are expected during normal operation.
 func BatchIndexScheduledTransactionID(w storage.Writer, scheduledTxID uint64, txID flow.Identifier) error {
 	return UpsertByKey(w, MakePrefix(codeTransactionIDByScheduledTransactionID, scheduledTxID), txID)
 }
 
-// BatchIndexScheduledTransactionBlockID indexes the scheduled transaction by its transaction ID and block ID.
+// BatchIndexScheduledTransactionBlockID indexes the scheduled transaction's block ID by its transaction ID.
 //
 // No errors are expected during normal operation.
 func BatchIndexScheduledTransactionBlockID(w storage.Writer, txID flow.Identifier, blockID flow.Identifier) error {

storage/store/scheduled_transactions.go

@@ -12,6 +12,10 @@ import (
 
 var _ storage.ScheduledTransactions = (*ScheduledTransactions)(nil)
 
+// ScheduledTransactions represents persistent storage for scheduled transaction indices.
+// Note: no scheduled transactions are stored. Transaction bodies can be generated on-demand using
+// the blueprints package. This interface provides access to indices used to lookup the block ID
+// that the scheduled transaction was executed in, which allows querying its transaction result.
 type ScheduledTransactions struct {
 	db           storage.DB
 	cacheTxID    *Cache[uint64, flow.Identifier]

utils/unittest/fixtures/transaction_result.go

@@ -74,7 +74,7 @@ func (g *TransactionResultGenerator) List(n int, opts ...TransactionResultOption
 	return list
 }
 
-// ForTransactions generates a list of [flow.TransactionResult] for multiple transactions.
+// ForTransactions generates a [flow.TransactionResult] for each of the provided transactions.
 func (g *TransactionResultGenerator) ForTransactions(transactions []*flow.TransactionBody, opts ...TransactionResultOption) []flow.TransactionResult {
 	list := make([]flow.TransactionResult, len(transactions))
 	for i, tx := range transactions {
@@ -148,7 +148,7 @@ func (g *LightTransactionResultGenerator) List(n int, opts ...LightTransactionRe
 	return list
 }
 
-// ForTransactions generates a list of [flow.LightTransactionResult] for multiple transactions.
+// ForTransactions generates a [flow.LightTransactionResult] for each of the provided transactions.
 func (g *LightTransactionResultGenerator) ForTransactions(transactions []*flow.TransactionBody, opts ...LightTransactionResultOption) []flow.LightTransactionResult {
 	list := make([]flow.LightTransactionResult, len(transactions))
 	for i, tx := range transactions {