Update stale doc comments to describe the slot-based move state

Author: soheilshahrouz

vpr/src/place/net_cost_handler.h

@@ -105,9 +105,10 @@ class NetCostHandler {
      *
      * The change in the bounding box cost is stored in `bb_delta_c`.
      * The change in the timing cost is stored in `timing_delta_c`.
-     * ts_nets_to_update is also extended with the latest net.
      *
-     * @return The number of affected nets.
+     * Every affected net is recorded in ts_nets_to_update_ and given a slot in
+     * ts_net_info_. The slots must be released by update_move_nets() or
+     * reset_move_nets() before this method is called again.
      */
     void find_affected_nets_and_update_costs(const PlaceDelayModel* delay_model,
                                              const PlacerCriticalities* criticalities,
@@ -116,14 +117,14 @@ class NetCostHandler {
                                              double& timing_delta_c);
 
     /**
-     * @brief Reset the net cost function flags (proposed_net_cost and bb_updated_before)
+     * @brief Discards the proposed state of the affected nets and releases their slots.
+     * Called when the move under evaluation is rejected.
      */
     void reset_move_nets();
 
     /**
-     * @brief Update net cost data structures (in placer context and net_cost in .cpp file)
-     * and reset flags (proposed_net_cost and bb_updated_before).
-     * It is used to determine the index up to which elements in ts_nets_to_update are valid.
+     * @brief Copies the proposed state of the affected nets into the committed state
+     * and releases their slots. Called when the move under evaluation is accepted.
      */
     void update_move_nets();
 

vpr/src/place/swap_evaluator.cpp

@@ -100,7 +100,7 @@ void SwapEvaluator::commit(t_pl_blocks_to_be_moved& blocks_affected,
         placer_state_.mutable_timing().commit_td_cost(blocks_affected);
     }
 
-    // Update net cost functions and reset flags.
+    // Commit the proposed net costs and release the scratch state of the move.
     net_cost_handler_.update_move_nets();
     if (update_interposer_costs) {
         interposer_cost_handler_->commit_costs(net_cost_handler_.affected_nets());
@@ -111,7 +111,7 @@ void SwapEvaluator::commit(t_pl_blocks_to_be_moved& blocks_affected,
 }
 
 void SwapEvaluator::revert(t_pl_blocks_to_be_moved& blocks_affected, bool revert_td) {
-    // Reset the net cost function flags first.
+    // Discard the proposed net state first.
     net_cost_handler_.reset_move_nets();
 
     // Restore the blk_loc_registry.block_locs data structures to their state before the move.