add comments to new lines

Signed-off-by: jitokim <[email protected]>

Author: jitokim

mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java

@@ -808,6 +808,17 @@ void setProtocolVersions(List<String> protocolVersions) {
 	private static final TypeReference<McpSchema.CompleteResult> COMPLETION_COMPLETE_RESULT_TYPE_REF = new TypeReference<>() {
 	};
 
+
+	/**
+	 * Sends a completion/complete request to generate value suggestions based on a given reference
+	 * and argument. This is typically used to provide auto-completion options for user input fields.
+	 *
+	 * @param completeRequest The request containing the prompt or resource reference and argument
+	 * for which to generate completions.
+	 * @return A Mono that completes with the result containing completion suggestions.
+	 * @see McpSchema.CompleteRequest
+	 * @see McpSchema.CompleteResult
+	 */
 	public Mono<McpSchema.CompleteResult> completeCompletion(McpSchema.CompleteRequest completeRequest) {
 		return this.withInitializationCheck("complete completions", initializedResult -> this.mcpSession
 			.sendRequest(McpSchema.METHOD_COMPLETION_COMPLETE, completeRequest, COMPLETION_COMPLETE_RESULT_TYPE_REF));

mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java

@@ -326,6 +326,12 @@ public void setLoggingLevel(McpSchema.LoggingLevel loggingLevel) {
 		this.delegate.setLoggingLevel(loggingLevel).block();
 	}
 
+	/**
+	 * Send a completion/complete request.
+	 * @param completeRequest the completion request contains the prompt or resource reference
+	 * and arguments for generating suggestions.
+	 * @return the completion result containing suggested values.
+	 */
 	public McpSchema.CompleteResult completeCompletion(McpSchema.CompleteRequest completeRequest) {
 		return this.delegate.completeCompletion(completeRequest).block();
 	}

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java

@@ -728,6 +728,7 @@ private McpServerSession.RequestHandler<McpSchema.CompleteResult> completionComp
 
 				String type = request.ref().type();
 
+				// check if the referenced resource exists
 				if (type.equals("ref/prompt")
 						&& request.ref() instanceof McpSchema.CompleteRequest.PromptReference promptReference) {
 					McpServerFeatures.AsyncPromptSpecification prompt = this.prompts.get(promptReference.name());
@@ -755,6 +756,17 @@ private McpServerSession.RequestHandler<McpSchema.CompleteResult> completionComp
 			};
 		}
 
+		/**
+		 * Parses the raw JSON-RPC request parameters into a {@link McpSchema.CompleteRequest} object.
+		 * <p>
+		 * This method manually extracts the `ref` and `argument` fields from the input map,
+		 * determines the correct reference type (either prompt or resource),
+		 * and constructs a fully-typed {@code CompleteRequest} instance.
+		 *
+		 * @param object the raw request parameters, expected to be a Map containing "ref" and "argument" entries.
+		 * @return a {@link McpSchema.CompleteRequest} representing the structured completion request.
+		 * @throws IllegalArgumentException if the "ref" type is not recognized.
+		 */
 		@SuppressWarnings("unchecked")
 		private McpSchema.CompleteRequest parseCompletionParams(Object object) {
 			Map<String, Object> params = (Map<String, Object>) object;

mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java

@@ -928,6 +928,15 @@ public SyncSpecification prompts(McpServerFeatures.SyncPromptSpecification... pr
 			return this;
 		}
 
+		/**
+		 * Registers multiple completions with their handlers using a List. This method is
+		 * useful when completions need to be added in bulk from a collection.
+		 *
+		 * @param completions List of completion specifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if completions is null
+		 * @see #completions(McpServerFeatures.SyncCompletionSpecification...)
+		 */
 		public SyncSpecification completions(List<McpServerFeatures.SyncCompletionSpecification> completions) {
 			Assert.notNull(completions, "Completions list must not be null");
 			for (McpServerFeatures.SyncCompletionSpecification completion : completions) {
@@ -936,6 +945,14 @@ public SyncSpecification completions(List<McpServerFeatures.SyncCompletionSpecif
 			return this;
 		}
 
+		/**
+		 * Registers multiple completions with their handlers using varargs. This method is
+		 * useful when completions are defined inline and added directly.
+		 *
+		 * @param completions Array of completion specifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if completions is null
+		 */
 		public SyncSpecification completions(McpServerFeatures.SyncCompletionSpecification... completions) {
 			Assert.notNull(completions, "Completions list must not be null");
 			for (McpServerFeatures.SyncCompletionSpecification completion : completions) {

mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java

@@ -339,9 +339,51 @@ static AsyncPromptSpecification fromSync(SyncPromptSpecification prompt) {
 		}
 	}
 
+	/**
+	 * Specification of a completion handler function with asynchronous execution support.
+	 * Completions generate AI model outputs based on prompt or resource references and
+	 * user-provided arguments. This abstraction enables:
+	 * <ul>
+	 * <li>Customizable response generation logic
+	 * <li>Parameter-driven template expansion
+	 * <li>Dynamic interaction with connected clients
+	 * </ul>
+	 *
+	 * <p>
+	 * Example completion specification: <pre>{@code
+	 * new McpServerFeatures.AsyncCompletionSpecification(
+	 *     (exchange, request) -> {
+	 *     	   String name = request.argument().name(); // e.g., "language"
+	 *         String language = request.argument().value(); // e.g., "py"
+	 *         List<String> suggestions = List.of(
+	 *         	   "python",
+	 *         	   "pytorch",
+	 *         	   "pyside"
+	 *         );
+	 *         CompleteResult.CompleteCompletion completion = new CompleteResult.CompleteCompletion(
+	 *             suggestions, suggestions.size(), false
+	 *         );
+	 *         return Mono.just(new CompleteResult(completion));
+	 *     }
+	 * )
+	 * }</pre>
+	 *
+	 * @param completionHandler The asynchronous function that processes completion requests
+	 * and returns results. The first argument is an {@link McpAsyncServerExchange}
+	 * used to interact with the client. The second argument is a
+	 * {@link io.modelcontextprotocol.spec.McpSchema.CompleteRequest}.
+	 */
 	public record AsyncCompletionSpecification(
 			BiFunction<McpAsyncServerExchange, McpSchema.CompleteRequest, Mono<McpSchema.CompleteResult>> completionHandler) {
 
+		/**
+		 * Converts a synchronous {@link SyncCompletionSpecification} into an
+		 * {@link AsyncCompletionSpecification} by wrapping the handler in a bounded elastic
+		 * scheduler for safe non-blocking execution.
+		 *
+		 * @param completion the synchronous completion specification
+		 * @return an asynchronous wrapper of the provided sync specification, or {@code null} if input is null
+		 */
 		static AsyncCompletionSpecification fromSync(SyncCompletionSpecification completion) {
 			if (completion == null) {
 				return null;
@@ -462,7 +504,27 @@ public record SyncCompletionSpecification(CompletionRefKey referenceKey,
 			BiFunction<McpSyncServerExchange, McpSchema.CompleteRequest, McpSchema.CompleteResult> completionHandler) {
 	}
 
+	/**
+	 * A unique key representing a completion reference, composed of its type and identifier.
+	 * This key is used to look up asynchronous completion specifications in a map-like structure.
+	 *
+	 * <p>The {@code type} typically corresponds to the kind of reference, such as
+	 * {@code "ref/prompt"} or {@code "ref/resource"}, while the {@code identifier} is the
+	 * name or URI associated with the specific reference.
+	 *
+	 * @param type the reference type (e.g., "ref/prompt", "ref/resource")
+	 * @param identifier the reference identifier (e.g., prompt name or resource URI)
+	 */
 	public record CompletionRefKey(String type, String identifier) {
+
+		/**
+		 * Creates a {@code CompletionRefKey} from a {@link McpSchema.CompleteRequest}.
+		 * The key is derived from the request's reference type and its associated name or URI.
+		 *
+		 * @param request the {@code CompleteRequest} containing a prompt or resource reference
+		 * @return a unique key based on the request's reference
+		 * @throws IllegalArgumentException if the reference type is unsupported
+		 */
 		public static CompletionRefKey from(McpSchema.CompleteRequest request) {
 			var ref = request.ref();
 			if (ref instanceof McpSchema.CompleteRequest.PromptReference pr) {