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 <[email protected]>
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 {
