chore: Fix Javadoc warnings in spec/ module

Author: kabir

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

@@ -1,17 +1,31 @@
 
 package io.a2a.spec;
 
+/**
+ * Constants defining the A2A protocol method names.
+ */
 public interface A2AMethods {
+    /** Method name for canceling a task. */
     String CANCEL_TASK_METHOD = "CancelTask";
+    /** Method name for deleting task push notification configuration. */
     String DELETE_TASK_PUSH_NOTIFICATION_CONFIG_METHOD = "DeleteTaskPushNotificationConfig";
+    /** Method name for getting extended agent card information. */
     String GET_EXTENDED_AGENT_CARD_METHOD = "GetExtendedAgentCard";
+    /** Method name for getting a task. */
     String GET_TASK_METHOD = "GetTask";
+    /** Method name for getting task push notification configuration. */
     String GET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD = "GetTaskPushNotificationConfig";
+    /** Method name for listing tasks. */
     String LIST_TASK_METHOD = "ListTasks";
+    /** Method name for listing task push notification configurations. */
     String LIST_TASK_PUSH_NOTIFICATION_CONFIG_METHOD = "ListTaskPushNotificationConfig";
+    /** Method name for sending a message. */
     String SEND_MESSAGE_METHOD = "SendMessage";
+    /** Method name for sending a streaming message. */
     String SEND_STREAMING_MESSAGE_METHOD = "SendStreamingMessage";
+    /** Method name for setting task push notification configuration. */
     String SET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD = "SetTaskPushNotificationConfig";
+    /** Method name for subscribing to task events. */
     String SUBSCRIBE_TO_TASK_METHOD = "SubscribeToTask";
 
 }

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

@@ -29,6 +29,9 @@ public record APIKeySecurityScheme(
     /**
      * Compact constructor with validation.
      *
+     * @param location the location where the API key is sent (required)
+     * @param name the name of the API key parameter (required)
+     * @param description a human-readable description (optional)
      * @throws IllegalArgumentException if location or name is null
      */
     public APIKeySecurityScheme {

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

@@ -49,6 +49,7 @@ public record DataPart(Map<String, Object> data) implements Part<Map<String, Obj
     /**
      * Compact constructor with validation and defensive copying.
      *
+     * @param data the structured data map (required, defensively copied for immutability)
      * @throws IllegalArgumentException if data is null
      */
     public DataPart {

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

@@ -49,6 +49,7 @@ public record FilePart(FileContent file) implements Part<FileContent> {
     /**
      * Compact constructor with validation.
      *
+     * @param file the file content (required, either FileWithBytes or FileWithUri)
      * @throws IllegalArgumentException if file is null
      */
     public FilePart {

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

@@ -47,6 +47,9 @@ public record HTTPAuthSecurityScheme(
     /**
      * Compact constructor with validation.
      *
+     * @param bearerFormat the bearer token format (optional)
+     * @param scheme the authentication scheme (required)
+     * @param description the scheme description (optional)
      * @throws IllegalArgumentException if scheme is null
      */
     public HTTPAuthSecurityScheme {

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

@@ -20,6 +20,8 @@ public record ListTaskPushNotificationConfigParams(String id, int pageSize, Stri
      * Validates that required parameters are not null.
      *
      * @param id the task identifier
+     * @param pageSize the maximum number of items to return per page
+     * @param pageToken the pagination token for the next page
      * @param tenant the tenant identifier
      */
     public ListTaskPushNotificationConfigParams {

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

@@ -47,6 +47,14 @@ public record Message(Role role, List<Part<?>> parts,
     /**
      * Compact constructor with validation and defensive copying.
      *
+     * @param role the role of the message sender (user or agent)
+     * @param parts the content parts of the message (text, file, or data)
+     * @param messageId the unique identifier for this message
+     * @param contextId the conversation context identifier
+     * @param taskId the task identifier this message is associated with
+     * @param referenceTaskIds list of reference task identifiers
+     * @param metadata additional metadata for the message
+     * @param extensions list of protocol extensions used in this message
      * @throws IllegalArgumentException if role, parts, or messageId is null, or if parts is empty
      */
     public Message {
@@ -80,6 +88,7 @@ public static Builder builder() {
      * Creates a new Builder initialized with values from an existing Message.
      *
      * @param message the Message to copy values from
+     * @return a new Builder instance initialized with the message's values
      */
     public static Builder builder(Message message) {
         return new Builder(message);

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

@@ -33,6 +33,9 @@ public record OAuth2SecurityScheme(
     /**
      * Compact constructor with validation.
      *
+     * @param flows the OAuth 2.0 flow configuration (required)
+     * @param description optional description of the security scheme
+     * @param oauth2MetadataUrl optional URL to OAuth 2.0 metadata (RFC 8414)
      * @throws IllegalArgumentException if flows is null
      */
     public OAuth2SecurityScheme {

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

@@ -41,6 +41,8 @@ public record OpenIdConnectSecurityScheme(
     /**
      * Compact constructor with validation.
      *
+     * @param openIdConnectUrl URL to the OpenID Connect Discovery document (required)
+     * @param description optional description of the security scheme
      * @throws IllegalArgumentException if openIdConnectUrl is null
      */
     public OpenIdConnectSecurityScheme {

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

@@ -59,6 +59,12 @@ public record Task(
     /**
      * Compact constructor with validation and defensive copying.
      *
+     * @param id the task identifier
+     * @param contextId the context identifier
+     * @param status the task status
+     * @param artifacts the list of artifacts produced by the task
+     * @param history the message history for this task
+     * @param metadata additional metadata for the task
      * @throws IllegalArgumentException if id, contextId, or status is null
      */
     public Task {
@@ -91,6 +97,7 @@ public static Builder builder() {
      * by copying all fields and then selectively updating specific values.
      *
      * @param task the Task to copy values from
+     * @return a new Builder instance initialized with the task's values
      */
     public static Builder builder(Task task) {
         return new Builder(task);