From 57b1c80b59b8685e0a59dc008efedc6a64ca75c8 Mon Sep 17 00:00:00 2001
From: Michael Nitschinger <mnitschinger@apple.com>
Date: Mon, 5 Aug 2024 15:53:32 +0200
Subject: [PATCH 1/3] capacity-limiter-api: polish javadocs

---
 .../limiter/api/AllowAllCapacityLimiter.java  |  6 +--
 .../capacity/limiter/api/CapacityLimiter.java | 43 +++++++++++--------
 .../limiter/api/CapacityLimiters.java         |  2 +-
 .../capacity/limiter/api/Classification.java  |  2 +-
 .../limiter/api/CompositeCapacityLimiter.java | 16 +++----
 5 files changed, 38 insertions(+), 31 deletions(-)

diff --git a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/AllowAllCapacityLimiter.java b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/AllowAllCapacityLimiter.java
index 89f8178a8d..35f67f8298 100644
--- a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/AllowAllCapacityLimiter.java
+++ b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/AllowAllCapacityLimiter.java
@@ -24,7 +24,7 @@
 final class AllowAllCapacityLimiter implements CapacityLimiter {
     static final CapacityLimiter INSTANCE = new AllowAllCapacityLimiter();
     private static final int UNSUPPORTED = -1;
-    private static final Ticket noOpToken = new DefaultTicket();
+    private static final Ticket DEFAULT_TICKET = new DefaultTicket();
 
     private AllowAllCapacityLimiter() {
         // Singleton
@@ -37,7 +37,7 @@ public String name() {
 
     @Override
     public Ticket tryAcquire(final Classification classification, @Nullable final ContextMap context) {
-        return noOpToken;
+        return DEFAULT_TICKET;
     }
 
     @Override
@@ -73,7 +73,7 @@ public int ignored() {
 
         @Override
         public int pending() {
-            return -1;
+            return UNSUPPORTED;
         }
 
         @Override
diff --git a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java
index 52e91cb5b8..c007b3bc07 100644
--- a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java
+++ b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java
@@ -21,31 +21,30 @@
 
 /**
  * A provider of capacity for a client or server.
- * <br><br>
+ * <p>
  * <h2>Capacity</h2>
  * Capacity for an entity is defined as the number of concurrent requests that it can process without significantly
  * affecting resource consumption or likelihood to successfully process in a timely manner given currently
  * available resources vs resources required to process the new request.
  * This capacity offered can be static or dynamic and the semantics of determination is left to implementations.
- * <br><br>
+ * <p>
  * <h2>Consumption</h2>
  * As the capacity is defined in terms of concurrent requests, as {@link #tryAcquire(Classification, ContextMap)
  * new requests are seen}, some portion of this capacity is deemed to be consumed till a subsequent callback marks
  * the end of processing for that request. Number of times that {@link #tryAcquire(Classification, ContextMap)}
  * is called without a corresponding termination callback is termed as demand.
- * <br><br>
+ * <p>
  * <h2>Request Lifetime</h2>
  * Request processing starts when {@link #tryAcquire(Classification, ContextMap)} is called and returns a non-null
  * {@link Ticket} and terminates when either one of the following occurs:
  * <ul>
- *     <li>When the request is successfully completed =&gt; (Default: {@link Ticket#completed()})
- *     <li>When the request fails due to an external capacity rejection i.e., dropped =&gt; (Default:
- *     {@link Ticket#dropped()})
- *     </li>
- *     <li>When the request fails due to a local error =&gt; (Default: {@link Ticket#failed(Throwable)})
- *     <li>When the request is cancelled (Default: {@link Ticket#dropped()})
+ *     <li>When the request is successfully completed (Default: {@link Ticket#completed()})</li>
+ *     <li>When the request fails due to an external capacity rejection i.e., dropped (Default:
+ *     {@link Ticket#dropped()})</li>
+ *     <li>When the request fails due to a local error (Default: {@link Ticket#failed(Throwable)})</li>
+ *     <li>When the request is cancelled (Default: {@link Ticket#ignored()})</li>
  * </ul>
- * <br>
+ * <p>
  * <h2>Request Classifications</h2>
  * Requests can be classified with different classes, that can be taken into consideration when a
  * {@link CapacityLimiter} implementation supports this.
@@ -57,6 +56,7 @@ public interface CapacityLimiter {
 
     /**
      * Identifying name for this {@link CapacityLimiter}.
+     *
      * @return the name of this {@link CapacityLimiter}.
      */
     String name();
@@ -75,19 +75,21 @@ public interface CapacityLimiter {
     Ticket tryAcquire(Classification classification, @Nullable ContextMap context);
 
     /**
-     * Representation of the state of the {@link CapacityLimiter} when a {@link Ticket} is issued.
+     * Representation of the state of the {@link CapacityLimiter} when the {@link Ticket} is issued.
      */
     interface LimiterState {
         /**
          * Returns the remaining allowance of the {@link CapacityLimiter} when the {@link Ticket} was issued.
+         *
          * @return the remaining allowance of the {@link CapacityLimiter} when the {@link Ticket} was issued.
          */
         int remaining();
 
         /**
-         * Returns the current pending (in use capacity) demand.
+         * Returns the current pending (in use capacity) demand when the {@link Ticket} was issued.
+         * <p>
          * If the pending is unknown a negative value i.e., -1 is allowed to express this.
-         * @return the current pending (in use capacity) demand.
+         * @return the current pending (in use capacity) demand when the {@link Ticket} was issued.
          */
         int pending();
     }
@@ -106,6 +108,7 @@ interface Ticket {
 
         /**
          * Representation of the state of the {@link CapacityLimiter} when this {@link Ticket} was issued.
+         *
          * @return the {@link LimiterState state} of the limiter at the time this {@link Ticket} was issued.
          */
         LimiterState state();
@@ -120,8 +123,10 @@ interface Ticket {
         int completed();
 
         /**
-         * Callback to indicate that a request was dropped externally (eg. peer rejection) due to capacity
-         * issues. Loss based algorithms tend to reduce the limit by a multiplier on such events.
+         * Callback to indicate that a request was dropped externally (e.g. peer rejection) due to capacity
+         * issues.
+         * <p>
+         * Note that loss-based algorithms tend to reduce the limit by a multiplier on such events.
          *
          * @return An integer as hint (if positive), that represents an estimated remaining capacity after
          * this {@link Ticket ticket's} terminal callback. If supported, a positive number means there is capacity.
@@ -130,8 +135,9 @@ interface Ticket {
         int dropped();
 
         /**
-         * Callback to indicate that a request has failed. Algorithms may choose to act upon failures ie. Circuit
-         * Breaking.
+         * Callback to indicate that a request has failed.
+         * <p>
+         * Algorithms may choose to act upon failures (i.e. Circuit Breaking).
          *
          * @param error the failure cause.
          * @return An integer as hint (if positive), that represents an estimated remaining capacity after
@@ -142,8 +148,9 @@ interface Ticket {
 
         /**
          * Callback to indicate that a request had not a capacity deterministic termination.
+         * <p>
          * Ignoring a {@link Ticket} is a way to indicate to the {@link CapacityLimiter} that this operation's
-         * termination, should not be considered towards a decision for modifying the limits. e.g., An algorithm that
+         * termination should not be considered towards a decision for modifying the limits. e.g., An algorithm that
          * measures delays (time start - time end), can use that to ignore a particular result from the feedback loop.
          *
          * @return An integer as hint (if positive), that represents an estimated remaining capacity after
diff --git a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiters.java b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiters.java
index fdd476e8fd..75a01b78c6 100644
--- a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiters.java
+++ b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiters.java
@@ -32,7 +32,7 @@ private CapacityLimiters() {
 
     /**
      * Returns a NO-OP {@link CapacityLimiter} that has no logic around acquiring or releasing a permit for a request;
-     * thus it allows everything to go through, similarly to a non-existing {@link CapacityLimiter}.
+     * thus it allows everything to go through, similar to a non-existing {@link CapacityLimiter}.
      * <p>
      * This {@link CapacityLimiter} allows for situations where partitioned configurations are in use through
      * a resilience filter, and you want to limit one partition but not necessary the other.
diff --git a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/Classification.java b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/Classification.java
index 3c2e375738..93d7e55388 100644
--- a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/Classification.java
+++ b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/Classification.java
@@ -28,7 +28,7 @@
  * future supported classifications. This is an implementation detail of the respective {@link CapacityLimiter}.
  * <p>
  * Classification is treated as a hint for a {@link CapacityLimiter} and are expected to be strictly respected,
- * they are a best effort approach to communicate user's desire to the {@link CapacityLimiter}.
+ * as they are the best effort approach to communicate user's desire to the {@link CapacityLimiter}.
  */
 @FunctionalInterface
 public interface Classification {
diff --git a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CompositeCapacityLimiter.java b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CompositeCapacityLimiter.java
index 6b8672992c..c2c55aac1c 100644
--- a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CompositeCapacityLimiter.java
+++ b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CompositeCapacityLimiter.java
@@ -53,8 +53,8 @@ public String name() {
     public Ticket tryAcquire(final Classification classification, @Nullable final ContextMap context) {
         Ticket[] results = null;
         int idx = 0;
-        for (CapacityLimiter provider : providers) {
-            Ticket ticket = provider.tryAcquire(classification, context);
+        for (final CapacityLimiter provider : providers) {
+            final Ticket ticket = provider.tryAcquire(classification, context);
             if (ticket != null) {
                 if (results == null) {
                     results = new Ticket[providers.size()];
@@ -74,7 +74,7 @@ public Ticket tryAcquire(final Classification classification, @Nullable final Co
         return compositeResult(results);
     }
 
-    private static int completed(Ticket[] results) {
+    private static int completed(final Ticket[] results) {
         int remaining = 1;
         for (Ticket ticket : results) {
             if (ticket == null) {
@@ -88,7 +88,7 @@ private static int completed(Ticket[] results) {
         return remaining;
     }
 
-    private static int failed(Throwable cause, Ticket[] results) {
+    private static int failed(final Throwable cause, final Ticket[] results) {
         int remaining = 1;
         for (Ticket ticket : results) {
             if (ticket == null) {
@@ -102,7 +102,7 @@ private static int failed(Throwable cause, Ticket[] results) {
         return remaining;
     }
 
-    private static int dropped(Ticket[] results) {
+    private static int dropped(final Ticket[] results) {
         int remaining = 1;
         for (Ticket ticket : results) {
             if (ticket == null) {
@@ -116,9 +116,9 @@ private static int dropped(Ticket[] results) {
         return remaining;
     }
 
-    private static int cancelled(Ticket[] results) {
+    private static int ignored(final Ticket[] results) {
         int remaining = 1;
-        for (Ticket ticket : results) {
+        for (final Ticket ticket : results) {
             if (ticket == null) {
                 break;
             }
@@ -156,7 +156,7 @@ public int dropped() {
 
             @Override
             public int ignored() {
-                return CompositeCapacityLimiter.cancelled(tickets);
+                return CompositeCapacityLimiter.ignored(tickets);
             }
         };
     }

From 176b729cf544f8f09d4c9642c753c541cd16fe0f Mon Sep 17 00:00:00 2001
From: Michael Nitschinger <mnitschinger@apple.com>
Date: Mon, 5 Aug 2024 16:01:31 +0200
Subject: [PATCH 2/3] javadoc fix

---
 .../servicetalk/capacity/limiter/api/CapacityLimiter.java | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java
index c007b3bc07..444e699130 100644
--- a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java
+++ b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java
@@ -21,19 +21,19 @@
 
 /**
  * A provider of capacity for a client or server.
- * <p>
+ * <p/>
  * <h2>Capacity</h2>
  * Capacity for an entity is defined as the number of concurrent requests that it can process without significantly
  * affecting resource consumption or likelihood to successfully process in a timely manner given currently
  * available resources vs resources required to process the new request.
  * This capacity offered can be static or dynamic and the semantics of determination is left to implementations.
- * <p>
+ * <p/>
  * <h2>Consumption</h2>
  * As the capacity is defined in terms of concurrent requests, as {@link #tryAcquire(Classification, ContextMap)
  * new requests are seen}, some portion of this capacity is deemed to be consumed till a subsequent callback marks
  * the end of processing for that request. Number of times that {@link #tryAcquire(Classification, ContextMap)}
  * is called without a corresponding termination callback is termed as demand.
- * <p>
+ * <p/>
  * <h2>Request Lifetime</h2>
  * Request processing starts when {@link #tryAcquire(Classification, ContextMap)} is called and returns a non-null
  * {@link Ticket} and terminates when either one of the following occurs:
@@ -44,7 +44,7 @@
  *     <li>When the request fails due to a local error (Default: {@link Ticket#failed(Throwable)})</li>
  *     <li>When the request is cancelled (Default: {@link Ticket#ignored()})</li>
  * </ul>
- * <p>
+ * <p/>
  * <h2>Request Classifications</h2>
  * Requests can be classified with different classes, that can be taken into consideration when a
  * {@link CapacityLimiter} implementation supports this.

From 423d481d934c1f5c8f77488fb2a986f0a1cefefd Mon Sep 17 00:00:00 2001
From: Michael Nitschinger <mnitschinger@apple.com>
Date: Mon, 5 Aug 2024 16:09:26 +0200
Subject: [PATCH 3/3] Make javadoc happy

---
 .../capacity/limiter/api/CapacityLimiter.java    | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java
index 444e699130..0ace3fcb7c 100644
--- a/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java
+++ b/servicetalk-capacity-limiter-api/src/main/java/io/servicetalk/capacity/limiter/api/CapacityLimiter.java
@@ -21,20 +21,20 @@
 
 /**
  * A provider of capacity for a client or server.
- * <p/>
- * <h2>Capacity</h2>
+ * <p>
+ * <strong>Capacity</strong>
  * Capacity for an entity is defined as the number of concurrent requests that it can process without significantly
  * affecting resource consumption or likelihood to successfully process in a timely manner given currently
  * available resources vs resources required to process the new request.
  * This capacity offered can be static or dynamic and the semantics of determination is left to implementations.
- * <p/>
- * <h2>Consumption</h2>
+ * <p>
+ * <strong>Consumption</strong>
  * As the capacity is defined in terms of concurrent requests, as {@link #tryAcquire(Classification, ContextMap)
  * new requests are seen}, some portion of this capacity is deemed to be consumed till a subsequent callback marks
  * the end of processing for that request. Number of times that {@link #tryAcquire(Classification, ContextMap)}
  * is called without a corresponding termination callback is termed as demand.
- * <p/>
- * <h2>Request Lifetime</h2>
+ * <p>
+ * <strong>Request Lifetime</strong>
  * Request processing starts when {@link #tryAcquire(Classification, ContextMap)} is called and returns a non-null
  * {@link Ticket} and terminates when either one of the following occurs:
  * <ul>
@@ -44,8 +44,8 @@
  *     <li>When the request fails due to a local error (Default: {@link Ticket#failed(Throwable)})</li>
  *     <li>When the request is cancelled (Default: {@link Ticket#ignored()})</li>
  * </ul>
- * <p/>
- * <h2>Request Classifications</h2>
+ * <p>
+ * <strong>Request Classifications</strong>
  * Requests can be classified with different classes, that can be taken into consideration when a
  * {@link CapacityLimiter} implementation supports this.
  * {@link Classification} is used as hint from the user of the importance of the incoming request, and are not