feat: Add Javadoc for the spec module (#466)

Fixes: #475

Author: kabir

spec/src/main/java/io/a2a/spec/A2AClientError.java

@@ -1,16 +1,48 @@
 package io.a2a.spec;
 
 /**
- * Base exception for A2A Client errors.
+ * Base exception for A2A client-specific error conditions.
+ * <p>
+ * This is a specialized exception hierarchy for client-side errors, distinct from
+ * {@link A2AClientException}. It is used for errors that occur during client SDK
+ * operations such as validation, state management, and protocol handling.
+ * <p>
+ * Specialized subclasses:
+ * <ul>
+ *   <li>{@link A2AClientHTTPError} - HTTP transport errors with status codes</li>
+ *   <li>{@link A2AClientJSONError} - JSON serialization/deserialization errors</li>
+ *   <li>{@link A2AClientInvalidStateError} - Invalid client state errors</li>
+ *   <li>{@link A2AClientInvalidArgsError} - Invalid argument errors</li>
+ * </ul>
+ *
+ * @see A2AClientException for general client exceptions
+ * @see A2AClientHTTPError for HTTP-specific errors
+ * @see A2AClientJSONError for JSON-specific errors
+ * @see A2AClientInvalidStateError for invalid state errors
+ * @see A2AClientInvalidArgsError for invalid argument errors
  */
 public class A2AClientError extends RuntimeException {
+    /**
+     * Constructs a new A2AClientError with no detail message.
+     */
     public A2AClientError() {
     }
 
+    /**
+     * Constructs a new A2AClientError with the specified detail message.
+     *
+     * @param message the detail message
+     */
     public A2AClientError(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a new A2AClientError with the specified detail message and cause.
+     *
+     * @param message the detail message
+     * @param cause the cause of this exception
+     */
     public A2AClientError(String message, Throwable cause) {
         super(message, cause);
     }

spec/src/main/java/io/a2a/spec/A2AClientException.java

@@ -1,22 +1,56 @@
 package io.a2a.spec;
 
 /**
- * Exception to indicate a general failure related to an A2A client.
+ * Exception indicating a client-side failure in A2A Protocol operations.
+ * <p>
+ * This exception is thrown by A2A client implementations when encountering errors
+ * during communication with agents, response validation, or client-side processing.
+ * <p>
+ * Common scenarios:
+ * <ul>
+ *   <li>Network communication failures</li>
+ *   <li>Invalid agent responses ({@link A2AClientError})</li>
+ *   <li>HTTP errors ({@link A2AClientHTTPError})</li>
+ *   <li>JSON parsing errors ({@link A2AClientJSONError})</li>
+ * </ul>
+ *
+ * @see A2AException for the base exception class
+ * @see A2AServerException for server-side errors
+ * @see A2AClientError for more specific client errors
  */
 public class A2AClientException extends A2AException {
 
+    /**
+     * Constructs a new A2AClientException with no detail message or cause.
+     */
     public A2AClientException() {
         super();
     }
 
+    /**
+     * Constructs a new A2AClientException with the specified detail message.
+     *
+     * @param msg the detail message
+     */
     public A2AClientException(final String msg) {
         super(msg);
     }
 
+    /**
+     * Constructs a new A2AClientException with the specified cause.
+     *
+     * @param cause the cause of this exception
+     */
     public A2AClientException(final Throwable cause) {
         super(cause);
     }
 
+    /**
+     * Constructs a new A2AClientException with the specified detail message and cause.
+     *
+     * @param msg the detail message
+     * @param cause the cause of this exception
+     */
     public A2AClientException(final String msg, final Throwable cause) {
         super(msg, cause);
     }

spec/src/main/java/io/a2a/spec/A2AClientHTTPError.java

@@ -2,6 +2,33 @@
 
 import io.a2a.util.Assert;
 
+/**
+ * Client exception indicating an HTTP transport error with a specific status code.
+ * <p>
+ * This exception is thrown when HTTP communication with an A2A agent fails,
+ * capturing both the HTTP status code and error message. It is used for non-2xx
+ * HTTP responses that don't contain valid A2A Protocol error responses.
+ * <p>
+ * Common HTTP status codes:
+ * <ul>
+ *   <li>4xx - Client errors (400 Bad Request, 401 Unauthorized, 404 Not Found, etc.)</li>
+ *   <li>5xx - Server errors (500 Internal Server Error, 503 Service Unavailable, etc.)</li>
+ * </ul>
+ * <p>
+ * Usage example:
+ * <pre>{@code
+ * if (response.statusCode() >= 400) {
+ *     throw new A2AClientHTTPError(
+ *         response.statusCode(),
+ *         "HTTP error: " + response.statusMessage(),
+ *         response.body()
+ *     );
+ * }
+ * }</pre>
+ *
+ * @see A2AClientError for the base client error class
+ * @see <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status">HTTP Status Codes</a>
+ */
 public class A2AClientHTTPError extends A2AClientError {
     private final int code;
     private final String message;

spec/src/main/java/io/a2a/spec/A2AClientInvalidArgsError.java

@@ -1,5 +1,30 @@
 package io.a2a.spec;
 
+/**
+ * Client exception indicating invalid arguments provided to a client operation.
+ * <p>
+ * This exception is thrown when parameters passed to A2A client SDK methods fail
+ * validation. This is distinct from {@link InvalidParamsError}, which represents
+ * server-side parameter validation errors.
+ * <p>
+ * Common scenarios:
+ * <ul>
+ *   <li>Null values for required parameters</li>
+ *   <li>Invalid parameter combinations</li>
+ *   <li>Parameter values outside acceptable ranges</li>
+ *   <li>Malformed URIs or identifiers</li>
+ * </ul>
+ * <p>
+ * Usage example:
+ * <pre>{@code
+ * if (agentUrl == null || agentUrl.isEmpty()) {
+ *     throw new A2AClientInvalidArgsError("agentUrl cannot be null or empty");
+ * }
+ * }</pre>
+ *
+ * @see A2AClientError for the base client error class
+ * @see InvalidParamsError for server-side parameter errors
+ */
 public class A2AClientInvalidArgsError extends A2AClientError {
 
     public A2AClientInvalidArgsError() {

spec/src/main/java/io/a2a/spec/A2AClientInvalidStateError.java

@@ -1,5 +1,29 @@
 package io.a2a.spec;
 
+/**
+ * Client exception indicating an invalid state for the requested operation.
+ * <p>
+ * This exception is thrown when a client operation is attempted while the client
+ * is in a state that doesn't permit that operation. This ensures proper sequencing
+ * and lifecycle management of client operations.
+ * <p>
+ * Common scenarios:
+ * <ul>
+ *   <li>Attempting to send messages before client initialization</li>
+ *   <li>Trying to cancel a task after the client connection is closed</li>
+ *   <li>Performing operations on a client that has been shut down</li>
+ *   <li>Violating client state machine transitions</li>
+ * </ul>
+ * <p>
+ * Usage example:
+ * <pre>{@code
+ * if (!client.isConnected()) {
+ *     throw new A2AClientInvalidStateError("Client not connected");
+ * }
+ * }</pre>
+ *
+ * @see A2AClientError for the base client error class
+ */
 public class A2AClientInvalidStateError extends A2AClientError {
 
     public A2AClientInvalidStateError() {

spec/src/main/java/io/a2a/spec/A2AClientJSONError.java

@@ -1,5 +1,30 @@
 package io.a2a.spec;
 
+/**
+ * Client exception indicating a JSON serialization or deserialization error.
+ * <p>
+ * This exception is thrown when the A2A client SDK encounters errors while
+ * parsing JSON responses from agents or serializing requests. This typically
+ * indicates:
+ * <ul>
+ *   <li>Malformed JSON in agent responses</li>
+ *   <li>Unexpected JSON structure or field types</li>
+ *   <li>Missing required JSON fields</li>
+ *   <li>JSON encoding/decoding errors</li>
+ * </ul>
+ * <p>
+ * Usage example:
+ * <pre>{@code
+ * try {
+ *     AgentCard card = objectMapper.readValue(json, AgentCard.class);
+ * } catch (JsonProcessingException e) {
+ *     throw new A2AClientJSONError("Failed to parse agent card", e);
+ * }
+ * }</pre>
+ *
+ * @see A2AClientError for the base client error class
+ * @see JSONParseError for protocol-level JSON errors
+ */
 public class A2AClientJSONError extends A2AClientError {
 
     public A2AClientJSONError() {

spec/src/main/java/io/a2a/spec/A2AError.java

@@ -1,4 +1,29 @@
 package io.a2a.spec;
 
+/**
+ * Marker interface for A2A Protocol error events.
+ * <p>
+ * This interface extends {@link Event} to allow errors to be transmitted as events
+ * in the A2A Protocol's event stream. All protocol-level errors implement this interface,
+ * enabling uniform error handling across both streaming and non-streaming communication.
+ * <p>
+ * A2A errors typically extend {@link JSONRPCError} to provide JSON-RPC 2.0 compliant
+ * error responses with standard error codes, messages, and optional additional data.
+ * <p>
+ * Common implementations include:
+ * <ul>
+ *   <li>{@link InvalidParamsError} - Invalid method parameters</li>
+ *   <li>{@link InvalidRequestError} - Malformed request</li>
+ *   <li>{@link MethodNotFoundError} - Unknown method</li>
+ *   <li>{@link InternalError} - Server-side error</li>
+ *   <li>{@link TaskNotFoundError} - Task does not exist</li>
+ *   <li>And others for specific protocol error conditions</li>
+ * </ul>
+ *
+ * @see Event for the base event interface
+ * @see JSONRPCError for the base error implementation
+ * @see <a href="https://www.jsonrpc.org/specification#error_object">JSON-RPC 2.0 Error Object</a>
+ * @see <a href="https://a2a-protocol.org/latest/">A2A Protocol Specification</a>
+ */
 public interface A2AError extends Event {
 }

spec/src/main/java/io/a2a/spec/A2AException.java

@@ -1,7 +1,21 @@
 package io.a2a.spec;
 
 /**
- * Exception to indicate a general failure related to the A2A protocol.
+ * Base exception for A2A Protocol-related failures.
+ * <p>
+ * This is the root exception class for all A2A Protocol exceptions, providing a common
+ * base type for exception handling. It extends {@link RuntimeException} to allow unchecked
+ * exception propagation throughout A2A client and server implementations.
+ * <p>
+ * Specialized subclasses:
+ * <ul>
+ *   <li>{@link A2AServerException} - Server-side failures</li>
+ *   <li>{@link A2AClientException} - Client-side failures</li>
+ * </ul>
+ *
+ * @see A2AServerException for server-side errors
+ * @see A2AClientException for client-side errors
+ * @see <a href="https://a2a-protocol.org/latest/">A2A Protocol Specification</a>
  */
 public class A2AException extends RuntimeException {
 

spec/src/main/java/io/a2a/spec/A2AServerException.java

@@ -1,7 +1,21 @@
 package io.a2a.spec;
 
 /**
- * Exception to indicate a general failure related to an A2A server.
+ * Exception indicating a server-side failure in A2A Protocol operations.
+ * <p>
+ * This exception is thrown by A2A server implementations when encountering errors
+ * during request processing, task execution, or other server-side operations.
+ * <p>
+ * Common scenarios:
+ * <ul>
+ *   <li>Agent execution failures</li>
+ *   <li>Task store persistence errors</li>
+ *   <li>Resource exhaustion or limits exceeded</li>
+ *   <li>Configuration errors</li>
+ * </ul>
+ *
+ * @see A2AException for the base exception class
+ * @see A2AClientException for client-side errors
  */
 public class A2AServerException extends A2AException {
 

spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java

@@ -12,7 +12,16 @@
 import static io.a2a.spec.APIKeySecurityScheme.API_KEY;
 
 /**
- * Defines a security scheme using an API key.
+ * API key security scheme for agent authentication.
+ * <p>
+ * This security scheme uses an API key that can be sent in a header, query parameter,
+ * or cookie to authenticate requests to the agent.
+ * <p>
+ * Corresponds to the OpenAPI "apiKey" security scheme type.
+ *
+ * @see SecurityScheme for the base interface
+ * @see <a href="https://spec.openapis.org/oas/v3.0.0#security-scheme-object">OpenAPI Security Scheme</a>
+ * @see <a href="https://a2a-protocol.org/latest/">A2A Protocol Specification</a>
  */
 @JsonTypeName(API_KEY)
 @JsonInclude(JsonInclude.Include.NON_ABSENT)