update some comments

consensus/state.go

@@ -1427,11 +1427,12 @@ func (cs *ConsensusState) addVote(vote *types.Vote, peerID p2p.ID) (added bool,
 		// If +2/3 prevotes for a block or nil for *any* round:
 		if blockID, ok := prevotes.TwoThirdsMajority(); ok {
 
-			// First, unlock if prevotes is a valid POL.
-			// `lockRound < POLRound <= unlockOrChangeLockRound (see spec)`
-			// NOTE: If `lockRound < POLRound` but `!(POLRound <=
-			// unlockOrChangeLockRound)`, we'll still enterNewRound(H,vote.R)
-			// and enterPrecommit(H,vote.R) to process it there.
+			// There was a polka!
+			// If we're locked but this is a recent polka, unlock.
+			// If it matches our ProposalBlock, update the ValidBlock
+
+			// Unlock if `cs.LockedRound < vote.Round <= cs.Round`
+			// NOTE: If vote.Round > cs.Round, we'll deal with it when we get to vote.Round
 			if (cs.LockedBlock != nil) &&
 				(cs.LockedRound < vote.Round) &&
 				(vote.Round <= cs.Round) &&
@@ -1445,6 +1446,8 @@ func (cs *ConsensusState) addVote(vote *types.Vote, peerID p2p.ID) (added bool,
 			}
 
 			// Update Valid* if we can.
+			// NOTE: our proposal block may be nil or not what received a polka..
+			// TODO: we may want to still update the ValidBlock and obtain it via gossipping
 			if !blockID.IsZero() &&
 				(cs.ValidRound < vote.Round) &&
 				(vote.Round <= cs.Round) &&
@@ -1453,9 +1456,6 @@ func (cs *ConsensusState) addVote(vote *types.Vote, peerID p2p.ID) (added bool,
 				cs.ValidRound = vote.Round
 				cs.ValidBlock = cs.ProposalBlock
 				cs.ValidBlockParts = cs.ProposalBlockParts
-				// TODO: We might want to update ValidBlock also in case we
-				// don't have that block yet, and obtain the required block
-				// using gossiping
 			}
 		}
 

types/block.go

@@ -124,7 +124,7 @@ func (b *Block) MakePartSet(partSize int) *PartSet {
 }
 
 // HashesTo is a convenience function that checks if a block hashes to the given argument.
-// A nil block never hashes to anything, and nothing hashes to a nil hash.
+// Returns false if the block is nil or the hash is empty.
 func (b *Block) HashesTo(hash []byte) bool {
 	if len(hash) == 0 {
 		return false

types/vote_set.go

@@ -404,8 +404,8 @@ func (voteSet *VoteSet) HasAll() bool {
 	return voteSet.sum == voteSet.valSet.TotalVotingPower()
 }
 
-// Returns either a blockhash (or nil) that received +2/3 majority.
-// If there exists no such majority, returns (nil, PartSetHeader{}, false).
+// If there was a +2/3 majority for blockID, return blockID and true.
+// Else, return the empty BlockID{} and false.
 func (voteSet *VoteSet) TwoThirdsMajority() (blockID BlockID, ok bool) {
 	if voteSet == nil {
 		return BlockID{}, false