[Docs][LoadBalancing] Add/Improve Javadocs for LoadSheddingStrategy i…

…mpls (apache#12180)

* [LoadBalancing] Add/Improve Javadocs for LoadSheddingStrategy impls

* Use present tense

Co-authored-by: Anonymitaet <[email protected]>

Co-authored-by: Anonymitaet <[email protected]>

pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/impl/OverloadShedder.java

@@ -35,11 +35,14 @@
 
 /**
  * Load shedding strategy which will attempt to shed exactly one bundle on brokers which are overloaded, that is, whose
- * maximum system resource usage exceeds loadBalancerBrokerOverloadedThresholdPercentage. A bundle will be recommended
- * for unloading off that broker if and only if the following conditions hold: The broker has at least two bundles
- * assigned and the broker has at least one bundle that has not been unloaded recently according to
+ * maximum system resource usage exceeds loadBalancerBrokerOverloadedThresholdPercentage. To see which resources are
+ * considered when determining the maximum system resource, see {@link LocalBrokerData#getMaxResourceUsage()}. A bundle
+ * is recommended for unloading off that broker if and only if the following conditions hold: The broker has at
+ * least two bundles assigned and the broker has at least one bundle that has not been unloaded recently according to
  * LoadBalancerSheddingGracePeriodMinutes. The unloaded bundle will be the most expensive bundle in terms of message
- * rate that has not been recently unloaded.
+ * rate that has not been recently unloaded. Note that this strategy does not take into account "underloaded" brokers
+ * when determining which bundles to unload. If you are looking for a strategy that spreads load evenly across
+ * all brokers, see {@link ThresholdShedder}.
  */
 public class OverloadShedder implements LoadSheddingStrategy {
 

pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/impl/ThresholdShedder.java

@@ -35,6 +35,18 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Load shedding strategy that unloads any broker that exceeds the average resource utilization of all brokers by a
+ * configured threshold. As a consequence, this strategy tends to distribute load among all brokers. It does this by
+ * first computing the average resource usage per broker for the whole cluster. The resource usage for each broker is
+ * calculated using the following method: {@link LocalBrokerData#getMaxResourceUsageWithWeight)}. The weights for each
+ * resource are configurable. Historical observations are included in the running average based on the broker's
+ * setting for loadBalancerHistoryResourcePercentage. Once the average resource usage is calculated, a broker's
+ * current/historical usage is compared to the average broker usage. If a broker's usage is greater than the average
+ * usage per broker plus the loadBalancerBrokerThresholdShedderPercentage, this load shedder proposes removing
+ * enough bundles to bring the unloaded broker 5% below the current average broker usage. Note that recently
+ * unloaded bundles are not unloaded again.
+ */
 public class ThresholdShedder implements LoadSheddingStrategy {
     private static final Logger log = LoggerFactory.getLogger(ThresholdShedder.class);