improvements per review

server/src/main/java/org/elasticsearch/cluster/routing/allocation/allocator/DesiredBalance.java

@@ -20,7 +20,7 @@
  * The desired balance of the cluster, indicating which nodes should hold a copy of each shard.
  *
  * @param lastConvergedIndex Identifies what input data the balancer computation round used to produce this {@link DesiredBalance}. See
- *                           {@link DesiredBalanceInput#index()} for details. Each reroute request gets assigned a monotonically increasing
+ *                           {@link DesiredBalanceInput#index()} for details. Each reroute request gets assigned a strictly increasing
  *                           sequence number, and the balancer, which runs async to reroute, uses the latest request's data to compute the
  *                           desired balance.
  * @param assignments a set of the (persistent) node IDs to which each {@link ShardId} should be allocated

server/src/main/java/org/elasticsearch/cluster/routing/allocation/allocator/DesiredBalanceReconciler.java

@@ -104,6 +104,13 @@ public DesiredBalanceReconciler(
         this.nodeAllocationStatsAndWeightsCalculator = nodeAllocationStatsAndWeightsCalculator;
     }
 
+    /**
+     * Applies a desired shard allocation to the routing table by initializing and relocating shards in the cluster state.
+     *
+     * @param desiredBalance The new desired cluster shard allocation
+     * @param allocation Cluster state information with which to make decisions, contains routing table metadata that will be modified to
+     *                   reach the given desired balance.
+     */
     public void reconcile(DesiredBalance desiredBalance, RoutingAllocation allocation) {
         var nodeIds = allocation.routingNodes().getAllNodeIds();
         allocationOrdering.retainNodes(nodeIds);

server/src/main/java/org/elasticsearch/cluster/routing/allocation/allocator/DesiredBalanceShardsAllocator.java

@@ -73,8 +73,7 @@ public class DesiredBalanceShardsAllocator implements ShardsAllocator {
     private final DesiredBalanceReconciler desiredBalanceReconciler;
     private final ContinuousComputation<DesiredBalanceInput> desiredBalanceComputation;
     /**
-     * Accepts listeners with an index value (see {#link #indexGenerator}) and run them whenever a DesiredBalance computation completes with
-     * an equal or greater index value.
+     * Saves and runs listeners after DesiredBalance computations complete.
      */
     private final PendingListenersQueue pendingListenersQueue;
     /**