fix doc

Author: tcoratger

src/lean_spec/subspecs/forkchoice/store.py

@@ -943,26 +943,31 @@ def produce_block_with_signatures(
         Raises:
             AssertionError: If validator lacks proposer authorization for slot.
         """
-        # Get parent block and state
+        # Get parent block and state to build upon
         store, head_root = self.get_proposal_head(slot)
         head_state = store.states[head_root]
 
-        # Validate proposer authorization
+        # Validate proposer authorization for this slo
         num_validators = Uint64(head_state.validators.count)
         assert is_proposer(validator_index, slot, num_validators), (
             f"Validator {validator_index} is not the proposer for slot {slot}"
         )
 
-        # Fixed-point attestation collection
+        # Initialize empty attestation set for iterative collection
         attestations: list[Attestation] = []
         signatures: list[Signature] = []
 
+        # Iteratively collect valid attestations using fixed-point algorithm
+        #
+        # Continue until no new attestations can be added to the block.
+        # This ensures we include the maximal valid attestation set.
         while True:
             # Compute post-state to check attestation validity (inline, no hash_tree_root)
             temp_block = Block(
                 slot=slot,
                 proposer_index=validator_index,
                 parent_root=head_root,
+                # Temporary; updated after state computation
                 state_root=Bytes32.zero(),
                 body=BlockBody(attestations=Attestations(data=attestations)),
             )