Add comments.

libraries/chain/block_header_state.cpp

@@ -130,6 +130,9 @@ void finish_next(const block_header_state& prev,
       auto lib = next_header_state.core.last_final_block_num();
       auto it = prev.finalizer_policies.begin();
       if (it->first > lib) {
+         // we have at least one `finalizer_policy` in our map, but none of these is
+         // due to become active of this block because lib has not advanced enough, so
+         // we just copy the multimap and keep using the same `active_finalizer_policy`
          next_header_state.finalizer_policies = prev.finalizer_policies;
       } else {
          while (it != prev.finalizer_policies.end() && it->first <= lib) {

libraries/chain/include/eosio/chain/block_header_state.hpp

@@ -20,6 +20,20 @@ namespace detail { struct schedule_info; };
 constexpr uint32_t light_header_protocol_version_major = 1;
 constexpr uint32_t light_header_protocol_version_minor = 0;
 
+// ------------------------------------------------------------------------------------------
+// this is used for tracking in-flight `finalizer_policy` changes, which have been requested,
+// but are not activated yet. This struct is associated to a block_number in the
+// `finalizer_policies` flat_multimap: `block_num => state, finalizer_policy`
+//
+// When state == proposed, the block_num identifies the block in which the new policy was
+// proposed via set_finalizers.
+//
+// When that block becomes final, according to the block_header_state's finality_core,
+// 1. the policy becomes pending
+// 2. its key `block_num,` in the proposer_policies multimap, is the current block
+//
+// When this current block itself becomes final, the policy becomes active.
+// ------------------------------------------------------------------------------------------
 struct finalizer_policy_tracker {
    enum class state_t { proposed = 0, pending };
    state_t               state;