chore: add code comment for spec entity

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

@@ -1,13 +1,35 @@
 package io.a2a.spec;
 
+/**
+ * Exception class representing errors that occur in A2A client operations.
+ * <p>
+ * This exception is thrown when client-side errors occur during A2A protocol
+ * interactions, such as communication failures, invalid responses, or
+ * protocol violations.
+ * </p>
+ */
 public class A2AClientError extends Exception {
+    /**
+     * Constructs a new A2AClientError with no detail message.
+     */
     public A2AClientError() {
     }
 
+    /**
+     * Constructs a new A2AClientError with the specified detail message.
+     *
+     * @param message the detail message explaining the error
+     */
     public A2AClientError(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a new A2AClientError with the specified detail message and cause.
+     *
+     * @param message the detail message explaining the error
+     * @param cause the underlying cause of this exception
+     */
     public A2AClientError(String message, Throwable cause) {
         super(message, cause);
     }

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

@@ -2,10 +2,26 @@
 
 import io.a2a.util.Assert;
 
+/**
+ * Exception class representing HTTP-specific errors that occur in A2A client operations.
+ * <p>
+ * This exception extends {@link A2AClientError} and provides additional information
+ * about HTTP-related failures, including the HTTP status code and error message.
+ * It is thrown when HTTP communication errors occur during A2A protocol interactions.
+ * </p>
+ */
 public class A2AClientHTTPError extends A2AClientError {
     private final int code;
     private final String message;
 
+    /**
+     * Constructs a new A2AClientHTTPError with the specified HTTP status code, message, and data.
+     *
+     * @param code the HTTP status code associated with this error
+     * @param message the error message describing the HTTP error
+     * @param data additional data associated with the error (currently unused but reserved for future use)
+     * @throws IllegalArgumentException if message is null
+     */
     public A2AClientHTTPError(int code, String message, Object data) {
         Assert.checkNotNullParam("code", code);
         Assert.checkNotNullParam("message", message);

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

@@ -1,14 +1,37 @@
 package io.a2a.spec;
 
+/**
+ * Exception class representing JSON-specific errors that occur in A2A client operations.
+ * <p>
+ * This exception extends {@link A2AClientError} and is thrown when JSON parsing,
+ * serialization, or deserialization errors occur during A2A protocol interactions.
+ * Common scenarios include malformed JSON responses, invalid JSON structure,
+ * or JSON schema validation failures.
+ * </p>
+ */
 public class A2AClientJSONError extends A2AClientError {
 
+    /**
+     * Constructs a new A2AClientJSONError with no detail message.
+     */
     public A2AClientJSONError() {
     }
 
+    /**
+     * Constructs a new A2AClientJSONError with the specified detail message.
+     *
+     * @param message the detail message explaining the JSON error
+     */
     public A2AClientJSONError(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a new A2AClientJSONError with the specified detail message and cause.
+     *
+     * @param message the detail message explaining the JSON error
+     * @param cause the underlying cause of this JSON error
+     */
     public A2AClientJSONError(String message, Throwable cause) {
         super(message, cause);
     }

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

@@ -1,4 +1,17 @@
 package io.a2a.spec;
 
+/**
+ * Marker interface for all A2A protocol error events.
+ * <p>
+ * This interface extends {@link Event} and serves as a common type for all
+ * error-related events in the A2A protocol. It provides a way to categorize
+ * and handle error events uniformly across the system.
+ * </p>
+ * <p>
+ * Implementations of this interface represent various types of errors that
+ * can occur during A2A protocol operations, such as validation errors,
+ * processing errors, or communication failures.
+ * </p>
+ */
 public interface A2AError extends Event {
 }

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

@@ -5,18 +5,37 @@
  */
 public class A2AServerException extends A2AException {
 
+    /**
+     * Constructs a new A2AServerException with no detail message.
+     */
     public A2AServerException() {
         super();
     }
 
+    /**
+     * Constructs a new A2AServerException with the specified detail message.
+     *
+     * @param msg the detail message explaining the server error
+     */
     public A2AServerException(final String msg) {
         super(msg);
     }
 
+    /**
+     * Constructs a new A2AServerException with the specified cause.
+     *
+     * @param cause the underlying cause of this server exception
+     */
     public A2AServerException(final Throwable cause) {
         super(cause);
     }
 
+    /**
+     * Constructs a new A2AServerException with the specified detail message and cause.
+     *
+     * @param msg the detail message explaining the server error
+     * @param cause the underlying cause of this server exception
+     */
     public A2AServerException(final String msg, final Throwable cause) {
         super(msg, cause);
     }

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

@@ -55,10 +55,27 @@ public static Location fromString(String location) {
         }
     }
 
+    /**
+     * Constructs a new APIKeySecurityScheme with the specified parameters.
+     *
+     * @param in the location of the API key (header, query, or cookie)
+     * @param name the name of the API key parameter
+     * @param description a description of the security scheme
+     */
     public APIKeySecurityScheme(String in, String name, String description) {
         this(in, name, description, API_KEY);
     }
 
+    /**
+     * Constructs a new APIKeySecurityScheme with the specified parameters.
+     * This constructor is used for JSON deserialization.
+     *
+     * @param in the location of the API key (header, query, or cookie)
+     * @param name the name of the API key parameter
+     * @param description a description of the security scheme
+     * @param type the type of security scheme (must be "apiKey")
+     * @throws IllegalArgumentException if the type is not "apiKey"
+     */
     @JsonCreator
     public APIKeySecurityScheme(@JsonProperty("in") String in, @JsonProperty("name") String name,
                                 @JsonProperty("description") String description, @JsonProperty("type") String type) {
@@ -79,38 +96,79 @@ public String getDescription() {
     }
 
 
+    /**
+     * Gets the location of the API key.
+     *
+     * @return the location where the API key should be placed (header, query, or cookie)
+     */
     public String getIn() {
         return in;
     }
 
+    /**
+     * Gets the name of the API key parameter.
+     *
+     * @return the parameter name for the API key
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Gets the type of this security scheme.
+     *
+     * @return the security scheme type (always "apiKey")
+     */
     public String getType() {
         return type;
     }
 
+    /**
+     * Builder class for constructing APIKeySecurityScheme instances.
+     */
     public static class Builder {
         private String in;
         private String name;
         private String description;
 
+        /**
+         * Sets the location of the API key.
+         *
+         * @param in the location where the API key should be placed (header, query, or cookie)
+         * @return this builder instance for method chaining
+         */
         public Builder in(String in) {
             this.in = in;
             return this;
         }
 
+        /**
+         * Sets the name of the API key parameter.
+         *
+         * @param name the parameter name for the API key
+         * @return this builder instance for method chaining
+         */
         public Builder name(String name) {
             this.name = name;
             return this;
         }
 
+        /**
+         * Sets the description of the security scheme.
+         *
+         * @param description a description of the security scheme
+         * @return this builder instance for method chaining
+         */
         public Builder description(String description) {
             this.description = description;
             return this;
         }
 
+        /**
+         * Builds and returns a new APIKeySecurityScheme instance.
+         *
+         * @return a new APIKeySecurityScheme with the configured parameters
+         */
         public APIKeySecurityScheme build() {
             return new APIKeySecurityScheme(in, name, description);
         }

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

@@ -6,40 +6,78 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 
 /**
- * An agent's capabilities.
+ * Represents the optional A2A protocol features and capabilities supported by an agent.
+ * These capabilities define what advanced features the agent can handle beyond basic messaging.
+ *
+ * @param streaming whether the agent supports streaming responses for real-time communication
+ * @param pushNotifications whether the agent can send push notifications to clients
+ * @param stateTransitionHistory whether the agent maintains and provides access to state transition history
+ * @param extensions list of additional extensions or custom capabilities supported by the agent
  */
 @JsonInclude(JsonInclude.Include.NON_ABSENT)
 @JsonIgnoreProperties(ignoreUnknown = true)
 public record AgentCapabilities(boolean streaming, boolean pushNotifications, boolean stateTransitionHistory,
                                 List<AgentExtension> extensions) {
 
+    /**
+     * Builder class for constructing {@link AgentCapabilities} instances.
+     */
     public static class Builder {
 
         private boolean streaming;
         private boolean pushNotifications;
         private boolean stateTransitionHistory;
         private List<AgentExtension> extensions;
 
+        /**
+         * Sets whether the agent supports streaming responses.
+         *
+         * @param streaming {@code true} if the agent supports streaming responses
+         * @return this builder instance
+         */
         public Builder streaming(boolean streaming) {
             this.streaming = streaming;
             return this;
         }
 
+        /**
+         * Sets whether the agent can send push notifications.
+         *
+         * @param pushNotifications {@code true} if the agent supports push notifications
+         * @return this builder instance
+         */
         public Builder pushNotifications(boolean pushNotifications) {
             this.pushNotifications = pushNotifications;
             return this;
         }
 
+        /**
+         * Sets whether the agent maintains state transition history.
+         *
+         * @param stateTransitionHistory {@code true} if the agent provides state transition history
+         * @return this builder instance
+         */
         public Builder stateTransitionHistory(boolean stateTransitionHistory) {
             this.stateTransitionHistory = stateTransitionHistory;
             return this;
         }
 
+        /**
+         * Sets the list of additional extensions supported by the agent.
+         *
+         * @param extensions the list of agent extensions
+         * @return this builder instance
+         */
         public Builder extensions(List<AgentExtension> extensions) {
             this.extensions = extensions;
             return this;
         }
 
+        /**
+         * Builds and returns a new {@link AgentCapabilities} instance with the configured properties.
+         *
+         * @return a new AgentCapabilities instance
+         */
         public AgentCapabilities build() {
             return new AgentCapabilities(streaming, pushNotifications, stateTransitionHistory, extensions);
         }