docs: fix typos and add documentation comments for some batcher public methods

Author: samlaf

op-alt-da/damock.go

@@ -40,7 +40,7 @@ func NewMockDAClient(log log.Logger) *MockDAClient {
 }
 
 // NewCountingGenericCommitmentMockDAClient creates a MockDAClient that uses counting commitments.
-// It's commitments are big-endian encoded uint16s of 0, 1, 2, etc. instead of actual hash or altda-layer related commitments.
+// Its commitments are big-endian encoded uint16s of 0, 1, 2, etc. instead of actual hash or altda-layer related commitments.
 // Used for testing to make sure we receive commitments in order following Holocene strict ordering rules.
 func NewCountingGenericCommitmentMockDAClient(log log.Logger) *MockDAClient {
 	return &MockDAClient{

op-batcher/batcher/channel.go

@@ -24,7 +24,7 @@ type channel struct {
 	channelBuilder *ChannelBuilder
 	// Temporary cache for altDACommitments that are received potentially out of order from the da layer.
 	// Map: first frameNumber in txData -> txData (that contains an altDACommitment)
-	// Once the txData containing altDANextFrame is received, it will be pulled out of the
+	// Once the txData containing altDAFrameCursor is received, it will be pulled out of the
 	// channel on the next driver iteration, and sent to L1.
 	altDACommitments map[uint16]txData
 	// Points to the next frame number to send to L1 in order to maintain holocene strict ordering rules.
@@ -56,6 +56,10 @@ func newChannel(log log.Logger, metr metrics.Metricer, cfg ChannelConfig, rollup
 	}
 }
 
+// CacheAltDACommitment caches the commitment received from the DA layer for the given txData.
+// We cannot submit it directly to L1 yet, as we need to make sure the commitments are submitted in order,
+// according to the holocene rules. Therefore, we cache the commitment and let the channelManager
+// decide when to pull them out of the channel and send them to L1.
 func (s *channel) CacheAltDACommitment(txData txData, commitment altda.CommitmentData) {
 	if commitment == nil {
 		panic("expected non-nil commitment")
@@ -189,7 +193,7 @@ func (c *channel) ID() derive.ChannelID {
 	return c.channelBuilder.ID()
 }
 
-// NextAltDACommitment checks if it has already receives the altDA commitment
+// NextAltDACommitment checks if it has already received the altDA commitment
 // of the txData whose first frame is altDAFrameCursor. If it has, it returns
 // the txData and true. Otherwise, it returns an empty txData and false.
 func (c *channel) NextAltDACommitment() (txData, bool) {
@@ -200,7 +204,7 @@ func (c *channel) NextAltDACommitment() (txData, bool) {
 		if len(txData.frames) == 0 {
 			panic("expected txData to have frames")
 		}
-		// update altDANextFrame to the first frame of the next txData
+		// update altDAFrameCursor to the first frame of the next txData
 		lastFrame := txData.frames[len(txData.frames)-1]
 		c.altDAFrameCursor = lastFrame.id.frameNumber + 1
 		// We also store it in pendingTransactions so that TxFailed can know

op-batcher/batcher/channel_manager.go

@@ -92,6 +92,9 @@ func (s *channelManager) pendingBlocks() int {
 	return s.blocks.Len() - s.blockCursor
 }
 
+// CacheAltDACommitment caches the commitment received from the DA layer for the given txData.
+// We cannot submit it directly to L1 yet, as we need to make sure the commitments are submitted in order,
+// according to the holocene rules. Therefore, we cache them and let the channelManager decide when to submit them.
 func (s *channelManager) CacheAltDACommitment(txData txData, commitment altda.CommitmentData) {
 	if len(txData.frames) == 0 {
 		panic("no frames in txData")
@@ -110,6 +113,9 @@ func (s *channelManager) CacheAltDACommitment(txData txData, commitment altda.Co
 	}
 }
 
+// AltDASubmissionFailed marks a DA submission as having failed to be submitted to the DA layer.
+// The frames will be pushed back into the corresponding channel such that they can be pulled again by the
+// driver main loop and resent to the DA layer.
 func (s *channelManager) AltDASubmissionFailed(_id txID) {
 	id := _id.String()
 	if channel, ok := s.txChannels[id]; ok {