You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by zh...@apache.org on 2026/07/20 09:43:26 UTC
(shardingsphere) branch master updated: Improve Javadoc guidance and remove redundant MCP prose (#39191)
This is an automated email from the ASF dual-hosted git repository.
terrymanu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 6ef2bbd714d Improve Javadoc guidance and remove redundant MCP prose (#39191)
6ef2bbd714d is described below
commit 6ef2bbd714d53cddf3e57afd2ac125ae88010715
Author: Liang Zhang <zh...@apache.org>
AuthorDate: Mon Jul 20 17:43:19 2026 +0800
Improve Javadoc guidance and remove redundant MCP prose (#39191)
- distinguish required Javadoc structure from actionable contract details
- remove repeated collection, inheritance, and annotation descriptions
- preserve concurrency, ownership, and protocol error semantics
---
AGENTS.md | 9 +++++++++
.../org/apache/shardingsphere/mcp/api/MCPRequestContext.java | 2 --
.../apache/shardingsphere/mcp/api/payload/MCPSuccessPayload.java | 5 ++---
.../org/apache/shardingsphere/mcp/spi/MCPHandlerProvider.java | 9 +--------
.../shardingsphere/mcp/support/MCPFeatureRequestContext.java | 2 --
.../mcp/support/protocol/payload/MCPMapPayload.java | 3 +--
6 files changed, 13 insertions(+), 17 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 4414b9ad287..a4ea8f7f0b1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -84,6 +84,15 @@ This guide is written **for AI coding agents only**. Follow it literally; improv
whether an existing boundary should catch and wrap it, and whether callers/tests actually depend on the declaration.
When changing code removes the last checked-exception source, remove stale `throws` from private and internal methods by default;
for public APIs, first apply the public contract propagation gate and document any compatibility reason for keeping the declaration.
+ - **Javadoc signal-to-noise gate**:
+ - Follow `CODE_OF_CONDUCT.md`: keep concise summaries and required `@param`, `@return`, and `@throws` tags for public APIs and SPIs; do not treat this baseline as meaningless repetition.
+ - Add prose beyond that baseline only for contracts not expressed by names, signatures, types, annotations, or repository conventions that affect caller or implementer behavior,
+ such as concurrency, lifecycle, blocking, state transitions, protocol or compatibility boundaries, and exception handling.
+ - Do not restate those visible facts or generic collection properties. In particular, do not add statements such as
+ `The returned collection may be empty, but must not be null or contain null elements.`
+ - Document an empty collection or another special return value only when it has domain meaning and requires the caller to act differently.
+ - Every extra sentence must map to a concrete caller action, implementer obligation, compatibility requirement, or failure-handling rule; otherwise remove it.
+ Review only Javadocs added or modified within the declared task scope.
- Do not add or keep Javadocs on methods that only override or implement a documented parent method.
Keep the public contract on the declaring API, SPI, or interface.
An overriding method should add Javadocs only when it documents implementation-specific behavior, stricter preconditions, side effects, exceptions, compatibility notes,
diff --git a/mcp/api/src/main/java/org/apache/shardingsphere/mcp/api/MCPRequestContext.java b/mcp/api/src/main/java/org/apache/shardingsphere/mcp/api/MCPRequestContext.java
index a39f5e5bc8f..8dbb981f5f2 100644
--- a/mcp/api/src/main/java/org/apache/shardingsphere/mcp/api/MCPRequestContext.java
+++ b/mcp/api/src/main/java/org/apache/shardingsphere/mcp/api/MCPRequestContext.java
@@ -30,8 +30,6 @@ public interface MCPRequestContext {
/**
* Get the identity of the current MCP session.
*
- * <p>The identity always contains the MCP session identifier. Trusted HTTP attribution is optional and does not represent authentication or authorization.</p>
- *
* @return MCP session identity
*/
MCPSessionIdentity getSessionIdentity();
diff --git a/mcp/api/src/main/java/org/apache/shardingsphere/mcp/api/payload/MCPSuccessPayload.java b/mcp/api/src/main/java/org/apache/shardingsphere/mcp/api/payload/MCPSuccessPayload.java
index a2807bcc5b7..26ec0946dc2 100644
--- a/mcp/api/src/main/java/org/apache/shardingsphere/mcp/api/payload/MCPSuccessPayload.java
+++ b/mcp/api/src/main/java/org/apache/shardingsphere/mcp/api/payload/MCPSuccessPayload.java
@@ -24,9 +24,8 @@ import java.util.Map;
/**
* Successful MCP application payload.
*
- * <p>Tool and resource handlers return this type when the MCP operation completed normally. A payload may still describe a negative domain result,
- * such as a failed database validation. Controlled execution failures should be reported by throwing {@link ShardingSphereMCPException};
- * the runtime converts those failures to the protocol-specific MCP error surface.</p>
+ * <p>Tool and resource handlers return this type for normal MCP completion, including negative domain results such as failed database validation.
+ * Report controlled execution failures with {@link ShardingSphereMCPException}; the runtime converts them to protocol-specific errors.</p>
*/
@FunctionalInterface
public interface MCPSuccessPayload {
diff --git a/mcp/api/src/main/java/org/apache/shardingsphere/mcp/spi/MCPHandlerProvider.java b/mcp/api/src/main/java/org/apache/shardingsphere/mcp/spi/MCPHandlerProvider.java
index e9ec1738eb5..f61cd1956d1 100644
--- a/mcp/api/src/main/java/org/apache/shardingsphere/mcp/spi/MCPHandlerProvider.java
+++ b/mcp/api/src/main/java/org/apache/shardingsphere/mcp/spi/MCPHandlerProvider.java
@@ -28,8 +28,7 @@ import java.util.Collection;
/**
* MCP handler provider.
*
- * <p>The provider is loaded as a singleton SPI. Handler instances returned by this provider are retained by the runtime and may be invoked concurrently.
- * Implementations must not retain request-scoped state.</p>
+ * <p>Handler instances returned by this provider are retained by the runtime and may be invoked concurrently.</p>
*/
@SingletonSPI
public interface MCPHandlerProvider extends ShardingSphereSPI {
@@ -37,8 +36,6 @@ public interface MCPHandlerProvider extends ShardingSphereSPI {
/**
* Get resource handlers.
*
- * <p>The returned collection may be empty, but must not be {@code null} or contain {@code null} elements.</p>
- *
* @return resource handlers
*/
Collection<MCPResourceHandler<?>> getResourceHandlers();
@@ -46,8 +43,6 @@ public interface MCPHandlerProvider extends ShardingSphereSPI {
/**
* Get tool handlers.
*
- * <p>The returned collection may be empty, but must not be {@code null} or contain {@code null} elements.</p>
- *
* @return tool handlers
*/
Collection<MCPToolHandler<?>> getToolHandlers();
@@ -55,8 +50,6 @@ public interface MCPHandlerProvider extends ShardingSphereSPI {
/**
* Get completion handlers.
*
- * <p>The returned collection may be empty, but must not be {@code null} or contain {@code null} elements.</p>
- *
* @return completion handlers
*/
Collection<MCPCompletionHandler<?>> getCompletionHandlers();
diff --git a/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/MCPFeatureRequestContext.java b/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/MCPFeatureRequestContext.java
index 9d979af04b5..552ee975273 100644
--- a/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/MCPFeatureRequestContext.java
+++ b/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/MCPFeatureRequestContext.java
@@ -29,8 +29,6 @@ import java.util.Optional;
/**
* MCP feature request context.
- *
- * <p>The runtime owns this context. Feature handlers and completion providers must use it only during the current synchronous invocation.</p>
*/
public interface MCPFeatureRequestContext extends MCPRequestContext {
diff --git a/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/protocol/payload/MCPMapPayload.java b/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/protocol/payload/MCPMapPayload.java
index 2cc5c4aeea3..3ef5cb3e317 100644
--- a/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/protocol/payload/MCPMapPayload.java
+++ b/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/protocol/payload/MCPMapPayload.java
@@ -25,8 +25,7 @@ import java.util.Map;
/**
* MCP payload adapter for a fully assembled successful payload.
*
- * <p>This thin adapter returns the supplied payload as-is. It does not copy, merge, normalize, validate against a tool schema,
- * classify errors, or build a transport envelope. Callers must finish constructing the payload before wrapping it and must not mutate it afterwards.</p>
+ * <p>The supplied payload is returned as-is. Callers must finish constructing it before wrapping and must not mutate it afterwards.</p>
*/
@RequiredArgsConstructor
public final class MCPMapPayload implements MCPSuccessPayload {