some cleanup

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/LoadBalancerBuilder.java

@@ -36,11 +36,11 @@
  * <p>
  * The created instances have the following behaviour:
  * <ul>
- *     <li>The load balancer will mark hosts unhealthy as determined by the configured {@link OutlierDetectorConfig}
- *     policy.</li>
  *     <li>Host selection is performed based upon the provided {@link LoadBalancingPolicy}. If no policy is provided
  *     the default policy is round-robin. While it can be policy specific, most policies will avoid unhealthy
  *     hosts.</li>
+ *     <li>Host health is determined by the configured {@link OutlierDetectorConfig}. This is inferred from the
+ *     results of requests and from actively probing for connectivity in accordance with the config.</li>
  *     <li>Connections are created lazily, without any concurrency control on their creation. This can lead to
  *     over-provisioning connections when dealing with a requests surge.</li>
  *     <li>Existing connections are reused unless a selector passed to
@@ -79,9 +79,13 @@ LoadBalancerBuilder<ResolvedAddress, C> loadBalancingPolicy(
 
     /**
      * Set the {@link OutlierDetectorConfig} to use with this load balancer.
+     * The outlier detection system works in conjunction with the load balancing policy to attempt to avoid hosts
+     * that have been determined to be unhealthy or slow. The details of the selection process are determined by the
+     * {@link LoadBalancingPolicy} while the health status is determined by the outlier detection configuration.
      * @param outlierDetectorConfig the {@link OutlierDetectorConfig} to use, or {@code null} to use the default
      *                              outlier detection.
      * @return {code this}
+     * @see #loadBalancingPolicy(LoadBalancingPolicy)
      */
     LoadBalancerBuilder<ResolvedAddress, C> outlierDetectorConfig(OutlierDetectorConfig outlierDetectorConfig);
 

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/NoopOutlierDetector.java

@@ -22,7 +22,8 @@
 
 import static java.util.Objects.requireNonNull;
 
-// A simple outlier detector implementation that only provides the basic `RequestTracker` implementation.
+// A simple outlier detector implementation that only provides the basic `RequestTracker` implementation
+// so the P2C LoadBalancingPolicy can still be effective.
 final class NoopOutlierDetector<ResolvedAddress, C extends LoadBalancedConnection>
         implements OutlierDetector<ResolvedAddress, C> {
 

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/OutlierDetectorConfig.java

@@ -376,7 +376,6 @@ public static final class Builder {
         private static final Duration DEFAULT_INTERVAL = ofSeconds(10);
         private static final Duration DEFAULT_BASE_EJECTION_TIME = ofSeconds(30);
         private static final int DEFAULT_MAX_EJECTION_PERCENTAGE = 10;
-
         private static final int DEFAULT_ENFORCING_CONSECUTIVE_5XX = 100;
         private static final int DEFAULT_ENFORCING_SUCCESS_RATE = 100;
         private static final int DEFAULT_SUCCESS_RATE_MINIMUM_HOSTS = 5;
@@ -388,8 +387,7 @@ public static final class Builder {
         private static final int DEFAULT_FAILURE_PERCENTAGE_REQUEST_VOLUME = 50;
         private static final Duration DEFAULT_MAX_EJECTION_TIME = ofSeconds(300);
 
-
-        // Non-xDS settings
+        // Non-xDS builder settings
         private Duration ewmaHalfLife = DEFAULT_EWMA_HALF_LIFE;
         private long ewmaCancellationPenalty = DEFAULT_CANCEL_PENALTY;
         private long ewmaErrorPenalty = DEFAULT_ERROR_PENALTY;
@@ -400,7 +398,11 @@ public static final class Builder {
 
         // True xDS settings
         private int consecutive5xx = DEFAULT_CONSECUTIVE_5XX;
-        // TODO: this is different from the default health check interval (10 seconds vs 5). It seems like 10 seconds would be the better default.
+
+        // Note that this value is shared by both the L4 and xDS health checking systems, but they had different
+        // default values (5s for L4 and 10s for xDS). We've decided to use the xDS default since it is viable for
+        // both whereas choosing 5s would necessitate changing a lot of related xDS settings such as min request
+        // volume, etc.
         private Duration interval = DEFAULT_INTERVAL;
 
         private Duration baseEjectionTime = DEFAULT_BASE_EJECTION_TIME;