chore: update javadocs

Signed-off-by: Marcos Tischer Vallim <tischer@gmail.com>

Author: mvallim

.opencode/skills/java-docs/SKILL.md

@@ -43,20 +43,6 @@ public class MyClass {
 - `@see` - Related documentation
 - `@deprecated` - Deprecation notice
 
-### 🎯 **Performance Indicators**
-
-#### **Mastery Levels**
-- **Beginner**: Basic Javadoc comments for public methods
-- **Intermediate**: Complete class and method documentation with all required tags
-- **Advanced**: Professional documentation with cross-references and examples
-
-#### **Quality Metrics**
-- 100% of public classes documented
-- 100% of public methods documented
-- Proper use of all required Javadoc tags
-- Consistent documentation style
-- No missing or incomplete documentation
-
 ### 🛠️ **Implementation Process**
 
 #### **Step 1: Class Documentation**
@@ -129,12 +115,6 @@ public User createUser(String username, String email)
 4. **Accuracy**: Keep documentation updated with code changes
 5. **Readability**: Use proper formatting and structure
 
-#### **Tools Integration**
-- IDE auto-completion support
-- Documentation generation tools
-- Continuous integration integration
-- Version control integration
-
 ### 📚 **Resources**
 
 #### **Reference Materials**
@@ -143,12 +123,6 @@ public User createUser(String username, String email)
 - Code style guidelines
 - Project documentation standards
 
-#### **Training Resources**
-- Javadoc tutorial examples
-- Documentation style guides
-- Code review checklists
-- Best practice workshops
-
 ### 🎯 **Expected Outcomes**
 - Professional quality code documentation
 - Maintainable and readable documentation
@@ -164,10 +138,3 @@ public User createUser(String username, String email)
 - Code clarity and quality
 - Tool integration effectiveness
 - Consistency across codebase
-
-### **Success Metrics**
-- 95%+ documentation coverage
-- Zero missing required tags
-- Positive code review feedback
-- Successful tool integration
-- Team adoption rate

amazon-sns-java-messaging-lib-template/README.md

@@ -59,7 +59,9 @@ com.amazon.sns.messaging.lib
 
 | Class                            | Description                                             |
 |----------------------------------|---------------------------------------------------------|
+| `PoisonRequestEntryException`    | Base exception for request entries that must be dropped. |
 | `MaximumAllowedMessageException` | Thrown when a single serialized message exceeds 256 KB. |
+| `JsonProcessingException`        | Thrown when a request payload fails to serialize to JSON. |
 
 ## Dependencies
 

amazon-sns-java-messaging-lib-template/src/main/java/com/amazon/sns/messaging/lib/concurrent/RingBufferBlockingQueue.java

@@ -158,7 +158,7 @@ private void signalProducer() {
    * Since the buffer capacity is always a power of two, wrapping is performed
    * efficiently using a bit mask instead of the modulo operator.
    *
-   * @param index the logical index to map
+   * @param sequence the logical index to map
    * @return the corresponding slot index in the backing array
    */
   private int index(final int sequence) {

amazon-sns-java-messaging-lib-template/src/main/java/com/amazon/sns/messaging/lib/core/AbstractAmazonSnsConsumer.java

@@ -172,6 +172,12 @@ private void publishBatch(final R publishBatchRequest) {
     }
   }
 
+  /**
+   * Fails the pending future of a poison request entry and removes it from the pending map.
+   *
+   * @param failRequestEntryException the exception describing why the entry is poison
+   * @param requestEntry              the request entry being dropped
+   */
   private void failPoisonRequestEntry(final PoisonRequestEntryException failRequestEntryException, final RequestEntry<E> requestEntry) {
     LOGGER.error("Failed to process request {}: {}", requestEntry.getId(), failRequestEntryException.getMessage(), failRequestEntryException);
 
@@ -287,7 +293,7 @@ private boolean canAddPayload(final int batchSizeBytes) {
    *
    * @param requests the request queue
    * @return an optional containing the assembled batch request, or empty
-   * @throws InterruptedException
+   * @throws InterruptedException if interrupted while waiting for queue elements
    */
   private Optional<R> createBatch(final BlockingQueue<RequestEntry<E>> requests) throws InterruptedException {
     final AtomicInteger batchSizeBytes = new AtomicInteger(0);

amazon-sns-java-messaging-lib-template/src/main/java/com/amazon/sns/messaging/lib/core/AbstractAmazonSnsProducer.java

@@ -89,6 +89,8 @@ public ListenableFuture<ResponseSuccessEntry, ResponseFailEntry> send(final Requ
   /**
    * Transitions the producer to the shutdown state. No further messages will be
    * accepted once shutdown.
+   *
+   * @param runnable the action to run after the producer enters the shutdown state
    */
   @Override
   public void shutdown(final Runnable runnable) {

amazon-sns-java-messaging-lib-template/src/main/java/com/amazon/sns/messaging/lib/core/AbstractAmazonSnsTemplate.java

@@ -104,6 +104,7 @@ public CompletableFuture<Void> await(final Duration timeout) {
    * For FIFO topics, a single-threaded pool is used to guarantee order.
    *
    * @param topicProperty the topic configuration
+   * @param meterRegistry the Micrometer meter registry for executor metrics
    * @return a configured thread pool executor
    */
   protected static ExecutorService getExecutorService(final TopicProperty topicProperty, final MeterRegistry meterRegistry) {
@@ -114,6 +115,19 @@ protected static ExecutorService getExecutorService(final TopicProperty topicPro
     );
   }
 
+  /**
+   * Fluent builder for constructing SDK-specific {@link AbstractAmazonSnsTemplate}
+   * implementations. Provides defaults for pending requests
+   * ({@link ConcurrentHashMap}), topic requests ({@link RingBufferBlockingQueue}),
+   * ObjectMapper, publish decorator (identity), and meter registry
+   * ({@link SimpleMeterRegistry}).
+   *
+   * @param <C> the Amazon SNS client type
+   * @param <R> the publish batch request type
+   * @param <O> the publish batch result type
+   * @param <E> the request entry payload type
+   * @param <T> the concrete template type
+   */
   @Getter(value = AccessLevel.PACKAGE)
   public static final class Builder<C, R, O, E, T extends AbstractAmazonSnsTemplate<R, O, E>> {
 

amazon-sns-java-messaging-lib-template/src/main/java/com/amazon/sns/messaging/lib/core/AmazonSnsProducer.java

@@ -41,6 +41,8 @@ public interface AmazonSnsProducer<E> {
 
   /**
    * Shuts down the producer, preventing any further messages from being accepted.
+   *
+   * @param runnable the action to run after the producer enters the shutdown state
    */
   public void shutdown(final Runnable runnable);
 

amazon-sns-java-messaging-lib-template/src/main/java/com/amazon/sns/messaging/lib/core/ListenableFuture.java

@@ -73,7 +73,7 @@ default void addCallback(final Consumer<? super S> successCallback) {
    * Mirrors the contract of {@link java.util.concurrent.Future#get()}: if the future
    * completed with a failure, this throws {@link ExecutionException} instead of returning.
    * The exception's cause is the {@link Throwable} carried by the failure result, if any
-   * (see {@link ResponseFailEntry#getThrowable()}), or a new exception built from the
+   * (see {@code ResponseFailEntry#getThrowable()}), or a new exception built from the
    * failure result's message otherwise.
    *
    * @return the success result

amazon-sns-java-messaging-lib-template/src/main/java/com/amazon/sns/messaging/lib/core/ListenableFutureImpl.java

@@ -73,6 +73,9 @@ class ListenableFutureImpl implements ListenableFuture<ResponseSuccessEntry, Res
     this.callbackExecutor = Objects.requireNonNull(callbackExecutor, "callbackExecutor cannot be null");
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public void addCallback(final Consumer<? super ResponseSuccessEntry> successCallback, final Consumer<? super ResponseFailEntry> failureCallback) {
     final Consumer<? super ResponseSuccessEntry> success = Optional.ofNullable(successCallback).orElse(identity()::apply);
@@ -87,20 +90,29 @@ public void addCallback(final Consumer<? super ResponseSuccessEntry> successCall
     }, callbackExecutor);
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public void success(final ResponseSuccessEntry entry) {
     if (not(delegate::complete).test(entry)) {
       throw new IllegalStateException("ListenableFuture already completed.");
     }
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public void fail(final ResponseFailEntry entry) {
     if (not(delegate::completeExceptionally).test(new FailureSignal(entry))) {
       throw new IllegalStateException("ListenableFuture already completed.");
     }
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public ResponseSuccessEntry get() throws InterruptedException, ExecutionException {
     try {
@@ -110,6 +122,9 @@ public ResponseSuccessEntry get() throws InterruptedException, ExecutionExceptio
     }
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public ResponseSuccessEntry get(final Duration timeout) throws InterruptedException, ExecutionException, TimeoutException {
     Objects.requireNonNull(timeout, "timeout cannot be null");

amazon-sns-java-messaging-lib-template/src/main/java/com/amazon/sns/messaging/lib/core/RequestEntryInternalFactory.java

@@ -67,7 +67,7 @@ public RequestEntryInternal create(final RequestEntry<?> requestEntry, final byt
    *
    * @param requestEntry the source request entry
    * @return a new internal request entry with serialized payload
-   * @throws PoisonRequestEntryException
+   * @throws PoisonRequestEntryException if the payload cannot be serialized
    */
   public RequestEntryInternal create(final RequestEntry<?> requestEntry) throws PoisonRequestEntryException {
     return create(requestEntry, convertPayload(requestEntry));
@@ -79,7 +79,7 @@ public RequestEntryInternal create(final RequestEntry<?> requestEntry) throws Po
    *
    * @param requestEntry the request entry whose payload to convert
    * @return the serialized payload bytes
-   * @throws PoisonRequestEntryException
+   * @throws PoisonRequestEntryException if the payload fails JSON serialization
    */
   public byte[] convertPayload(final RequestEntry<?> requestEntry) throws PoisonRequestEntryException {
     try {