chore: add docstrings to chainsegment

Author: ezdac

rolling-shutter/medley/chainsync/chainsegment/chain.go

@@ -32,6 +32,10 @@ type UpdateLatestResult struct {
 	UpdatedSegment *ChainSegment
 }
 
+// capNumPollBlocks is a pipeline function
+// that restricts the number of blocks to be
+// polled, e.g. during filling gaps between
+// two chain-segments.
 func capNumPollBlocks(num int) int {
 	if num > MaxNumPollBlocks {
 		return MaxNumPollBlocks
@@ -45,8 +49,6 @@ type ChainSegment struct {
 	chain []*types.Header
 }
 
-// assumes reverse order, and that it is
-// a connected chain-segment.
 func NewChainSegment(chain ...*types.Header) *ChainSegment {
 	bc := &ChainSegment{
 		chain: chain,
@@ -91,16 +93,31 @@ func (bc *ChainSegment) Copy() *ChainSegment {
 	return NewChainSegment(bc.chain...)
 }
 
+// UpdateLatest incorporates a new chainsegment `update` into it's existing
+// chain-segment.
+// For this it backtracks the new chain-segment until it finds the common ancestor
+// with it's current chain-segment. If there is no ancestor because of a block-number
+// gap between the old segments "latest" block and the new segments "earliest" block,
+// it will incrementally batch-augment the 'update' chain-segment with blocks older than
+// it's "earliest" block, and call the UpdateLatest latest method recursively
+// until the algorithm finds a common ancestor.
+// The outcome of this process is an `UpdateLatestResult`, which
+// communicates to the caller what part of the previous chain-segment had to be removed,
+// and what part of the `update` chain-segment was appended to the previous chain-segment
+// after removal of out-of-date blocks, in addition to the full newly updated chain-segment.
+// This is a pointer method that updates the internal state of it's chain-segment!
 func (bc *ChainSegment) UpdateLatest(ctx context.Context, c client.Sync, update *ChainSegment) (UpdateLatestResult, error) {
 	update = update.Copy()
 	if bc.Len() == 0 {
+		// We can't compare anything - instead of silently absorbing the
+		// whole new segment, communicate this to the caller with a specific error.
 		return UpdateLatestResult{}, ErrEmpty
 	}
 
 	if bc.Earliest().Number.Cmp(update.Earliest().Number) == 1 {
-		// We don't reach so far in the past.
-		// This only happens when the cache of used blocks in
-		// doesn't reach so far.
+		// We don't reach so far in the past for the old chain-segment.
+		// This happens when there is a large reorg, while the chain-segment
+		// of the cache is still small.
 		return UpdateLatestResult{}, fmt.Errorf(
 			"segment earliest=%d, update earliest=%d: %w",
 			bc.Earliest().Number.Int64(), update.Earliest().Number.Int64(),
@@ -143,12 +160,22 @@ func (bc *ChainSegment) UpdateLatest(ctx context.Context, c client.Sync, update
 		return bc.UpdateLatest(ctx, c, update)
 	}
 	// implicit case - overlap > 0:
+	// now we can compare the segments and find the common ancestor
+	// Return the segment of the overlap from the current segment
+	// and compute the diff of the whole new update segment.
 	removed, updated := bc.GetLatest(overlap).DiffLeftAligned(update)
+	// don't copy, but use the method's struct,
+	// that way we modify in-place
 	full := bc
 	if removed != nil {
+		// cut the reorged section that has to be removed
+		// so that we only have the "left" section up until the
+		// common ancestor
 		full = full.GetEarliest(full.Len() - removed.Len())
 	}
 	if updated != nil {
+		// and now append the update section
+		// to the right, effectively removing the reorged section
 		full.AddRight(updated)
 	}
 	return UpdateLatestResult{
@@ -158,11 +185,28 @@ func (bc *ChainSegment) UpdateLatest(ctx context.Context, c client.Sync, update
 	}, nil
 }
 
+// AddRight adds the `add` chain-segment to the "right" of the
+// original chain-segment, and thus assumes that the `add` segments
+// Earliest() block is the child-block of the original segments
+// Latest() block. This condition is *not* checked,
+// so callers have to guarantee for it.
 func (bc *ChainSegment) AddRight(add *ChainSegment) *ChainSegment {
 	bc.chain = append(bc.chain, add.chain...)
 	return bc
 }
 
+// DiffLeftAligned compares the ChainSegment to another chain-segment that
+// starts at the same Earliest() block-number.
+// It walks both segments from earliest to latest header simultaneously
+// and compares the block-hashes. As soon as there is a mismatch
+// in block-hashes, a consecutive difference from that point on is assumed.
+// All diff blocks from the `other` chain-segment will be appended to the returned `update`
+// chain-segment, and all diff blocks from the original chain-segment
+// will be appended to the `remove` chain-segment.
+// If there is no overlap in the diff, but the `other` chain-segment is longer than
+// the original segment, the `remove` segment will be nil, and the `update` segment
+// will consist of the non-overlapping blocks of the `other` segment.
+// If both segments are identical, both `update` and `remove` segments will be nil.
 func (bc *ChainSegment) DiffLeftAligned(other *ChainSegment) (remove, update *ChainSegment) {
 	// 1) assumes both segments start at the same block height (earliest block at index 0 with same blocknum)
 	// 2) assumes the other.Len() >= bc.Len()