From cea6b4ad98ca66df2bc6d837e6fcfaa3258357dd Mon Sep 17 00:00:00 2001
From: Ludovic Orban <lorban@bitronix.be>
Date: Wed, 26 Jun 2024 09:58:07 +0200
Subject: [PATCH] #11932 improve javadoc

Signed-off-by: Ludovic Orban <lorban@bitronix.be>
---
 .../eclipse/jetty/util/IteratingCallback.java   | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java
index 6fc58187dbb..fb3b1ae7e42 100644
--- a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java
+++ b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java
@@ -168,7 +168,12 @@ public abstract class IteratingCallback implements Callback
     protected abstract Action process() throws Throwable;
 
     /**
-     * Invoked when one task has completed successfully.
+     * Invoked when one task has completed successfully, either by the
+     * caller thread or by the processing thread. This invocation is
+     * always serialized w.r.t the execution of {@link #process()}.
+     * <p>
+     * This method is not invoked when a call to {@link #abort(Throwable)}
+     * is made before the {@link #succeeded()} callback happens.
      */
     protected void onSuccess()
     {
@@ -352,8 +357,11 @@ public abstract class IteratingCallback implements Callback
     /**
      * Method to invoke when the asynchronous sub-task succeeds.
      * <p>
-     * Subclasses that override this method must always remember
-     * to call {@code super.succeeded()}.
+     * This method should be considered final for all practical purposes.
+     * <p>
+     * Eventually, {@link #onSuccess()} is
+     * called, either by the caller thread or by the processing
+     * thread.
      */
     @Override
     public final void succeeded()
@@ -399,8 +407,7 @@ public abstract class IteratingCallback implements Callback
      * or to fail the overall asynchronous task and therefore
      * terminate the iteration.
      * <p>
-     * Subclasses that override this method must always remember
-     * to call {@code super.failed(Throwable)}.
+     * This method should be considered final for all practical purposes.
      * <p>
      * Eventually, {@link #onCompleteFailure(Throwable)} is
      * called, either by the caller thread or by the processing