docs: Add comprehensive javadoc to server-common module

- Fix @param error in PushNotificationConfigStore (blocking javadoc build)
- Add complete javadoc to EventQueue and all public/protected members
- Add javadoc to EventEnqueueHook, EventQueueClosedException
- Add javadoc to TaskStore, JSONRPCException, NoTaskQueueException
- Add javadoc to InMemoryTaskStore, Internal annotation
- Fix typo in PushNotificationConfigStore ("emty" -> "empty")

Reduces javadoc errors from 1 to 0 and warnings from 101 to 100.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Author: ehsavoie

server-common/src/main/java/io/a2a/server/JSONRPCException.java

@@ -2,13 +2,30 @@
 
 import io.a2a.spec.JSONRPCError;
 
+/**
+ * Exception wrapper for JSON-RPC protocol errors.
+ * <p>
+ * This exception encapsulates a {@link JSONRPCError} for handling
+ * protocol-level errors during JSON-RPC request processing.
+ * </p>
+ */
 public class JSONRPCException extends Exception{
     private final JSONRPCError error;
 
+    /**
+     * Creates a JSONRPCException wrapping the specified error.
+     *
+     * @param error the JSON-RPC error
+     */
     public JSONRPCException(JSONRPCError error) {
         this.error = error;
     }
 
+    /**
+     * Returns the wrapped JSON-RPC error.
+     *
+     * @return the JSON-RPC error
+     */
     public JSONRPCError getError() {
         return error;
     }

server-common/src/main/java/io/a2a/server/events/EventEnqueueHook.java

@@ -1,5 +1,15 @@
 package io.a2a.server.events;
 
+/**
+ * Hook interface for event queue enqueue operations.
+ * Implementations can be notified when items are enqueued to the event queue,
+ * allowing for custom behavior such as event replication or logging.
+ */
 public interface EventEnqueueHook {
+    /**
+     * Called when an item is enqueued to the event queue.
+     *
+     * @param item the event queue item being enqueued
+     */
     void onEnqueue(EventQueueItem item);
 }

server-common/src/main/java/io/a2a/server/events/EventQueue.java

@@ -16,21 +16,50 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Abstract base class for event queues that manage task event streaming.
+ * <p>
+ * An EventQueue provides a thread-safe mechanism for enqueueing and dequeueing events
+ * related to task execution. It supports backpressure through semaphore-based throttling
+ * and hierarchical queue structures via MainQueue and ChildQueue implementations.
+ * </p>
+ * <p>
+ * Use {@link #builder()} to create configured instances or extend MainQueue/ChildQueue directly.
+ * </p>
+ */
 public abstract class EventQueue implements AutoCloseable {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(EventQueue.class);
 
+    /**
+     * Default maximum queue size for event queues.
+     */
     public static final int DEFAULT_QUEUE_SIZE = 1000;
 
     private final int queueSize;
+    /**
+     * Internal blocking queue for storing event queue items.
+     */
     protected final BlockingQueue<EventQueueItem> queue = new LinkedBlockingDeque<>();
+    /**
+     * Semaphore for backpressure control, limiting the number of pending events.
+     */
     protected final Semaphore semaphore;
     private volatile boolean closed = false;
 
+    /**
+     * Creates an EventQueue with the default queue size.
+     */
     protected EventQueue() {
         this(DEFAULT_QUEUE_SIZE);
     }
 
+    /**
+     * Creates an EventQueue with the specified queue size.
+     *
+     * @param queueSize the maximum number of events that can be queued
+     * @throws IllegalArgumentException if queueSize is less than or equal to 0
+     */
     protected EventQueue(int queueSize) {
         if (queueSize <= 0) {
             throw new IllegalArgumentException("Queue size must be greater than 0");
@@ -40,6 +69,11 @@ protected EventQueue(int queueSize) {
         LOGGER.trace("Creating {} with queue size: {}", this, queueSize);
     }
 
+    /**
+     * Creates an EventQueue as a child of the specified parent queue.
+     *
+     * @param parent the parent event queue
+     */
     protected EventQueue(EventQueue parent) {
         this(DEFAULT_QUEUE_SIZE);
         LOGGER.trace("Creating {}, parent: {}", this, parent);
@@ -49,40 +83,82 @@ static EventQueueBuilder builder() {
         return new EventQueueBuilder();
     }
 
+    /**
+     * Builder for creating configured EventQueue instances.
+     * <p>
+     * Supports configuration of queue size, enqueue hooks, task association,
+     * close callbacks, and task state providers.
+     * </p>
+     */
     public static class EventQueueBuilder {
         private int queueSize = DEFAULT_QUEUE_SIZE;
         private @Nullable EventEnqueueHook hook;
         private @Nullable String taskId;
         private List<Runnable> onCloseCallbacks = new java.util.ArrayList<>();
         private @Nullable TaskStateProvider taskStateProvider;
 
+        /**
+         * Sets the maximum queue size.
+         *
+         * @param queueSize the maximum number of events that can be queued
+         * @return this builder
+         */
         public EventQueueBuilder queueSize(int queueSize) {
             this.queueSize = queueSize;
             return this;
         }
 
+        /**
+         * Sets the enqueue hook for event replication or logging.
+         *
+         * @param hook the hook to be invoked when items are enqueued
+         * @return this builder
+         */
         public EventQueueBuilder hook(EventEnqueueHook hook) {
             this.hook = hook;
             return this;
         }
 
+        /**
+         * Associates this queue with a specific task ID.
+         *
+         * @param taskId the task identifier
+         * @return this builder
+         */
         public EventQueueBuilder taskId(String taskId) {
             this.taskId = taskId;
             return this;
         }
 
+        /**
+         * Adds a callback to be executed when the queue is closed.
+         *
+         * @param onCloseCallback the callback to execute on close
+         * @return this builder
+         */
         public EventQueueBuilder addOnCloseCallback(Runnable onCloseCallback) {
             if (onCloseCallback != null) {
                 this.onCloseCallbacks.add(onCloseCallback);
             }
             return this;
         }
 
+        /**
+         * Sets the task state provider for tracking task finalization.
+         *
+         * @param taskStateProvider the task state provider
+         * @return this builder
+         */
         public EventQueueBuilder taskStateProvider(TaskStateProvider taskStateProvider) {
             this.taskStateProvider = taskStateProvider;
             return this;
         }
 
+        /**
+         * Builds and returns the configured EventQueue.
+         *
+         * @return a new MainQueue instance
+         */
         public EventQueue build() {
             if (hook != null || !onCloseCallbacks.isEmpty() || taskStateProvider != null) {
                 return new MainQueue(queueSize, hook, taskId, onCloseCallbacks, taskStateProvider);
@@ -92,18 +168,48 @@ public EventQueue build() {
         }
     }
 
+    /**
+     * Returns the configured queue size.
+     *
+     * @return the maximum number of events that can be queued
+     */
     public int getQueueSize() {
         return queueSize;
     }
 
+    /**
+     * Waits for the queue poller to start consuming events.
+     * This method blocks until signaled by {@link #signalQueuePollerStarted()}.
+     *
+     * @throws InterruptedException if the thread is interrupted while waiting
+     */
     public abstract void awaitQueuePollerStart() throws InterruptedException ;
 
+    /**
+     * Signals that the queue poller has started consuming events.
+     * This unblocks any threads waiting in {@link #awaitQueuePollerStart()}.
+     */
     public abstract void signalQueuePollerStarted();
 
+    /**
+     * Enqueues an event for processing.
+     *
+     * @param event the event to enqueue
+     */
     public void enqueueEvent(Event event) {
         enqueueItem(new LocalEventQueueItem(event));
     }
 
+    /**
+     * Enqueues an event queue item for processing.
+     * <p>
+     * This method will block if the queue is full, waiting to acquire a semaphore permit.
+     * If the queue is closed, the event will not be enqueued and a warning will be logged.
+     * </p>
+     *
+     * @param item the event queue item to enqueue
+     * @throws RuntimeException if interrupted while waiting to acquire the semaphore
+     */
     public void enqueueItem(EventQueueItem item) {
         Event event = item.getEvent();
         if (closed) {
@@ -121,6 +227,16 @@ public void enqueueItem(EventQueueItem item) {
         LOGGER.debug("Enqueued event {} {}", event instanceof Throwable ? event.toString() : event, this);
     }
 
+    /**
+     * Creates a child queue that shares events with this queue.
+     * <p>
+     * For MainQueue: creates a ChildQueue that receives all events enqueued to the parent.
+     * For ChildQueue: throws IllegalStateException (only MainQueue can be tapped).
+     * </p>
+     *
+     * @return a new ChildQueue instance
+     * @throws IllegalStateException if called on a ChildQueue
+     */
     public abstract EventQueue tap();
 
     /**
@@ -172,12 +288,24 @@ public void enqueueItem(EventQueueItem item) {
         }
     }
 
+    /**
+     * Placeholder method for task completion notification.
+     * Currently not used as BlockingQueue.poll()/take() automatically remove events.
+     */
     public void taskDone() {
         // TODO Not sure if needed yet. BlockingQueue.poll()/.take() remove the events.
     }
 
+    /**
+     * Closes this event queue gracefully, allowing pending events to be consumed.
+     */
     public abstract void close();
 
+    /**
+     * Closes this event queue with control over immediate shutdown.
+     *
+     * @param immediate if true, clears all pending events immediately; if false, allows graceful drain
+     */
     public abstract void close(boolean immediate);
 
     /**
@@ -191,14 +319,28 @@ public void taskDone() {
      */
     public abstract void close(boolean immediate, boolean notifyParent);
 
+    /**
+     * Checks if this queue has been closed.
+     *
+     * @return true if the queue is closed, false otherwise
+     */
     public boolean isClosed() {
         return closed;
     }
 
+    /**
+     * Internal method to close the queue gracefully.
+     * Delegates to {@link #doClose(boolean)} with immediate=false.
+     */
     protected void doClose() {
         doClose(false);
     }
 
+    /**
+     * Internal method to close the queue with control over immediate shutdown.
+     *
+     * @param immediate if true, clears all pending events immediately; if false, allows graceful drain
+     */
     protected void doClose(boolean immediate) {
         synchronized (this) {
             if (closed) {

server-common/src/main/java/io/a2a/server/events/EventQueueClosedException.java

@@ -1,4 +1,8 @@
 package io.a2a.server.events;
 
+/**
+ * Exception thrown when attempting to dequeue from a closed and empty event queue.
+ * This signals to consumers that no more events will be available from the queue.
+ */
 public class EventQueueClosedException extends Exception {
 }

server-common/src/main/java/io/a2a/server/events/NoTaskQueueException.java

@@ -1,21 +1,56 @@
 package io.a2a.server.events;
 
+/**
+ * Exception thrown when attempting to access a task queue that does not exist.
+ * <p>
+ * This exception is typically thrown when trying to retrieve or operate on
+ * an event queue for a task that has not been created or has been removed.
+ * </p>
+ */
 public class NoTaskQueueException extends RuntimeException {
+    /**
+     * Creates a NoTaskQueueException with no message.
+     */
     public NoTaskQueueException() {
     }
 
+    /**
+     * Creates a NoTaskQueueException with the specified detail message.
+     *
+     * @param message the detail message
+     */
     public NoTaskQueueException(String message) {
         super(message);
     }
 
+    /**
+     * Creates a NoTaskQueueException with the specified detail message and cause.
+     *
+     * @param message the detail message
+     * @param cause the cause
+     */
     public NoTaskQueueException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    /**
+     * Creates a NoTaskQueueException with the specified cause.
+     *
+     * @param cause the cause
+     */
     public NoTaskQueueException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * Creates a NoTaskQueueException with the specified message, cause,
+     * suppression enabled or disabled, and writable stack trace enabled or disabled.
+     *
+     * @param message the detail message
+     * @param cause the cause
+     * @param enableSuppression whether suppression is enabled or disabled
+     * @param writableStackTrace whether the stack trace should be writable
+     */
     public NoTaskQueueException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
         super(message, cause, enableSuppression, writableStackTrace);
     }

server-common/src/main/java/io/a2a/server/tasks/InMemoryTaskStore.java

@@ -14,6 +14,17 @@
 import io.a2a.spec.Task;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * In-memory implementation of {@link TaskStore} and {@link TaskStateProvider}.
+ * <p>
+ * This implementation uses a {@link ConcurrentHashMap} to store tasks in memory.
+ * Tasks are lost on application restart. For persistent storage, use a database-backed
+ * implementation such as the JPA TaskStore in the extras module.
+ * </p>
+ * <p>
+ * This is the default TaskStore used when no other implementation is provided.
+ * </p>
+ */
 @ApplicationScoped
 public class InMemoryTaskStore implements TaskStore, TaskStateProvider {