fix: Add Javadoc for rest transport server-side components (a2aproject#678)

Fixes: a2aproject#480

---------

Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
Co-authored-by: Emmanuel Hugonnet <ehugonne@redhat.com>

Author: kabir

reference/rest/src/main/java/io/a2a/server/rest/quarkus/A2AServerRoutes.java

@@ -3,6 +3,61 @@
 import io.a2a.server.ServerCallContext;
 import io.vertx.ext.web.RoutingContext;
 
+/**
+ * Factory interface for creating {@link ServerCallContext} from Vert.x routing context.
+ *
+ * <p>This interface provides an extension point for customizing how {@link ServerCallContext}
+ * instances are created in Quarkus REST applications. The default implementation in
+ * {@link A2AServerRoutes} extracts standard information (user, headers, tenant, protocol version),
+ * but applications can provide their own implementation to add custom context data.
+ *
+ * <h2>Default Behavior</h2>
+ * <p>When no CDI bean implementing this interface is provided, {@link A2AServerRoutes}
+ * creates contexts with:
+ * <ul>
+ *   <li>User authentication from Quarkus Security</li>
+ *   <li>HTTP headers map</li>
+ *   <li>Tenant ID from URL path</li>
+ *   <li>A2A protocol version from {@code X-A2A-Version} header</li>
+ *   <li>Required extensions from {@code X-A2A-Extensions} header</li>
+ * </ul>
+ *
+ * <h2>Custom Implementation Example</h2>
+ * <pre>{@code
+ * @ApplicationScoped
+ * public class CustomCallContextFactory implements CallContextFactory {
+ *     @Override
+ *     public ServerCallContext build(RoutingContext rc) {
+ *         // Extract custom data from routing context
+ *         String orgId = rc.request().getHeader("X-Organization-ID");
+ *
+ *         Map<String, Object> state = new HashMap<>();
+ *         state.put("organization", orgId);
+ *         state.put("requestId", UUID.randomUUID().toString());
+ *
+ *         return new ServerCallContext(
+ *             extractUser(rc),
+ *             state,
+ *             extractExtensions(rc),
+ *             extractVersion(rc)
+ *         );
+ *     }
+ * }
+ * }</pre>
+ *
+ * @see ServerCallContext
+ * @see A2AServerRoutes#createCallContext(RoutingContext, String)
+ */
 public interface CallContextFactory {
+    /**
+     * Builds a {@link ServerCallContext} from a Vert.x routing context.
+     *
+     * <p>This method is called for each incoming HTTP request to create the context
+     * that will be passed to the {@link io.a2a.server.requesthandlers.RequestHandler}
+     * and eventually to the {@link io.a2a.server.agentexecution.AgentExecutor}.
+     *
+     * @param rc the Vert.x routing context containing request data
+     * @return a new ServerCallContext with extracted authentication, headers, and metadata
+     */
     ServerCallContext build(RoutingContext rc);
 }

reference/rest/src/main/java/io/a2a/server/rest/quarkus/CallContextFactory.java

@@ -3,7 +3,30 @@
 import io.a2a.server.TransportMetadata;
 import io.a2a.spec.TransportProtocol;
 
+/**
+ * Transport metadata implementation for Quarkus REST.
+ *
+ * <p>This class provides transport protocol identification for the Quarkus REST
+ * reference implementation. It reports {@link TransportProtocol#HTTP_JSON} as
+ * the transport protocol, indicating that this implementation uses HTTP with
+ * JSON payloads for the A2A protocol.
+ *
+ * <p>The transport metadata is used by the framework for:
+ * <ul>
+ *   <li>Logging and monitoring (identifying which transport handled a request)</li>
+ *   <li>Protocol negotiation and version compatibility checks</li>
+ *   <li>Metrics and telemetry (transport-specific performance tracking)</li>
+ * </ul>
+ *
+ * @see TransportMetadata
+ * @see TransportProtocol
+ */
 public class QuarkusRestTransportMetadata implements TransportMetadata {
+    /**
+     * Returns the transport protocol identifier.
+     *
+     * @return {@code "http+json"} indicating HTTP transport with JSON encoding
+     */
     @Override
     public String getTransportProtocol() {
         return TransportProtocol.HTTP_JSON.asString();

reference/rest/src/main/java/io/a2a/server/rest/quarkus/QuarkusRestTransportMetadata.java

@@ -1,3 +1,65 @@
+/**
+ * Quarkus REST reference implementation for the A2A protocol.
+ *
+ * <p>This package provides a ready-to-use Quarkus-based REST transport implementation
+ * that maps HTTP endpoints to A2A protocol operations. It serves as both a reference
+ * implementation and a production-ready solution for deploying A2A agents over HTTP/REST.
+ *
+ * <h2>Key Components</h2>
+ * <ul>
+ *   <li>{@link A2AServerRoutes} - Vert.x route definitions mapping HTTP paths to A2A operations</li>
+ *   <li>{@link CallContextFactory} - Extensible factory for creating {@link io.a2a.server.ServerCallContext}</li>
+ *   <li>{@link QuarkusRestTransportMetadata} - Transport protocol metadata implementation</li>
+ * </ul>
+ *
+ * <h2>Architecture</h2>
+ * <pre>
+ * HTTP Request (Quarkus/Vert.x)
+ *     ↓
+ * A2AServerRoutes (@Route methods)
+ *     ↓
+ * RestHandler (transport/rest)
+ *     ↓
+ * RequestHandler (server-common)
+ *     ↓
+ * AgentExecutor (user implementation)
+ * </pre>
+ *
+ * <h2>Supported Endpoints</h2>
+ * <ul>
+ *   <li>{@code POST /message:send} - Send message (blocking)</li>
+ *   <li>{@code POST /message:stream} - Send message (streaming SSE)</li>
+ *   <li>{@code GET /tasks} - List tasks</li>
+ *   <li>{@code GET /tasks/{taskId}} - Get task by ID</li>
+ *   <li>{@code POST /tasks/{taskId}:cancel} - Cancel task</li>
+ *   <li>{@code POST /tasks/{taskId}:subscribe} - Subscribe to task updates (SSE)</li>
+ *   <li>{@code GET /.well-known/agent-card.json} - Get agent card</li>
+ * </ul>
+ *
+ * <h2>Multi-tenancy Support</h2>
+ * <p>All endpoints support optional tenant prefixes in the URL path:
+ * <ul>
+ *   <li>{@code /message:send} - Default tenant (empty string)</li>
+ *   <li>{@code /tenant-123/message:send} - Tenant "tenant-123"</li>
+ * </ul>
+ *
+ * <h2>Usage</h2>
+ * <p>Add this module as a dependency to your Quarkus project:
+ * <pre>{@code
+ * <dependency>
+ *   <groupId>io.github.a2asdk</groupId>
+ *   <artifactId>a2a-java-sdk-reference-rest</artifactId>
+ *   <version>${a2a.version}</version>
+ * </dependency>
+ * }</pre>
+ *
+ * <p>Provide CDI beans for {@link io.a2a.spec.AgentCard} and
+ * {@link io.a2a.server.agentexecution.AgentExecutor}, and the REST endpoints
+ * will be automatically registered.
+ *
+ * @see io.a2a.transport.rest.handler
+ * @see io.a2a.server.requesthandlers
+ */
 @NullMarked
 package io.a2a.server.rest.quarkus;
 

reference/rest/src/main/java/io/a2a/server/rest/quarkus/package-info.java

@@ -3,8 +3,20 @@
 /**
  * Shared REST context keys for A2A protocol data.
  *
- * These keys provide access to REST context information,
- * enabling rich context access in service method implementations.
+ * <p>These keys provide access to REST context information stored in
+ * {@link io.a2a.server.ServerCallContext}, enabling rich context access
+ * in service method implementations and middleware.
+ *
+ * <h2>Usage Example</h2>
+ * <pre>{@code
+ * public void processRequest(ServerCallContext context) {
+ *     String tenant = context.get(RestContextKeys.TENANT_KEY);
+ *     String method = context.get(RestContextKeys.METHOD_NAME_KEY);
+ *     Map<String, String> headers = context.get(RestContextKeys.HEADERS_KEY);
+ * }
+ * }</pre>
+ *
+ * @see io.a2a.server.ServerCallContext
  */
 public final class RestContextKeys {