Improve javadoc clarity

Author: loicrouchon

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/listener/BackPressureHandler.java

@@ -41,9 +41,9 @@ public interface BackPressureHandler {
 	 * Releases the specified amount of permits for processed messages. Each message that has been processed should
 	 * release one permit, whether processing was successful or not.
 	 * <p>
-	 * This method can is called in the following use cases:
+	 * This method can be called in the following use cases:
 	 * <ul>
-	 * <li>{@link ReleaseReason#LIMITED}: permits were not used because another BackPressureHandler has a lower permits
+	 * <li>{@link ReleaseReason#LIMITED}: all/some permits were not used because another BackPressureHandler has a lower permits
 	 * limit and the difference in permits needs to be returned.</li>
 	 * <li>{@link ReleaseReason#NONE_FETCHED}: none of the permits were actually used because no messages were retrieved
 	 * from SQS. Permits need to be returned.</li>
@@ -82,16 +82,16 @@ default void release(int amount) {
 
 	enum ReleaseReason {
 		/**
-		 * Permits were not used because another BackPressureHandler has a lower permits limit and the difference need
-		 * to be aligned across all handlers.
+		 * All/Some permits were not used because another BackPressureHandler has a lower permits limit and the
+		 * permits difference need to be aligned across all handlers.
 		 */
 		LIMITED,
 		/**
 		 * No messages were retrieved from SQS, so all permits need to be returned.
 		 */
 		NONE_FETCHED,
 		/**
-		 * Some messages were fetched from SQS. Unused permits need to be returned.
+		 * Some messages were fetched from SQS. Unused permits if any need to be returned.
 		 */
 		PARTIAL_FETCH,
 		/**

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/listener/BackPressureHandlerFactory.java

@@ -16,11 +16,13 @@
 package io.awspring.cloud.sqs.listener;
 
 /**
- * A factory for creating {@link BackPressureHandler} for managing queue consumption backpressure. Implementations can
- * configure each the {@link BackPressureHandler} according to its strategies, using the provided
- * {@link ContainerOptions}.
+ * Factory interface for creating {@link BackPressureHandler} instances to manage queue consumption backpressure.
  * <p>
- * A set of default implementations are provided by the {@link BackPressureHandlerFactories} class.
+ * Implementations of this interface are responsible for producing a new {@link BackPressureHandler} for each
+ * container, configured according to the provided {@link ContainerOptions}. This ensures that internal resources
+ * (such as counters or semaphores) are not shared across containers, which could lead to unintended side effects.
+ * <p>
+ * Default factory implementations can be found in the {@link BackPressureHandlerFactories} class.
  */
 public interface BackPressureHandlerFactory {
 

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/listener/ContainerOptions.java

@@ -130,7 +130,7 @@ default BackOffPolicy getPollBackOffPolicy() {
 	BackPressureMode getBackPressureMode();
 
 	/**
-	 * Return the a {@link BackPressureHandlerFactory} to create a {@link BackPressureHandler} for this container.
+	 * Return the {@link BackPressureHandlerFactory} to create a {@link BackPressureHandler} for this container.
 	 * @return the BackPressureHandlerFactory.
 	 */
 	BackPressureHandlerFactory getBackPressureHandlerFactory();