From 1eedab5915588f1b28345d52ace2cea591515941 Mon Sep 17 00:00:00 2001
From: shiguangtong <shiguangtong@users.noreply.github.com>
Date: Sat, 28 Mar 2026 20:38:09 +0800
Subject: [PATCH] docs: Add package-level Javadoc for gateway core packages

- Add comprehensive Javadoc for org.springframework.cloud.gateway.discovery package
  describing service discovery integration capabilities
- Add Javadoc for org.springframework.cloud.gateway.event package
  documenting event-driven gateway lifecycle management
- Add Javadoc for org.springframework.cloud.gateway.filter package
  explaining filter types and common implementations

These additions improve code documentation and help developers understand
the purpose and usage of each package in the Spring Cloud Gateway framework.
---
 .../cloud/gateway/discovery/package-info.java | 24 +++++++++++-
 .../cloud/gateway/event/package-info.java     | 28 +++++++++++++-
 .../cloud/gateway/filter/package-info.java    | 37 +++++++++++++++++--
 3 files changed, 82 insertions(+), 7 deletions(-)

diff --git a/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/discovery/package-info.java b/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/discovery/package-info.java
index f454e0ee68..75227aea45 100644
--- a/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/discovery/package-info.java
+++ b/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/discovery/package-info.java
@@ -15,9 +15,29 @@
  */
 
 /**
- * TODO: package javadoc.
+ * Service discovery integration for Spring Cloud Gateway.
+ *
+ * <p>
+ * This package provides support for dynamic route discovery using Spring Cloud's
+ * {@link org.springframework.cloud.client.discovery.DiscoveryClient}. It enables
+ * automatic route creation based on registered service instances in service registries
+ * such as Eureka, Consul, or Kubernetes.
+ * </p>
+ *
+ * <p>
+ * Key components:
+ * <ul>
+ * <li>{@link org.springframework.cloud.gateway.discovery.DiscoveryClientRouteDefinitionLocator}
+ * - Locates route definitions from discovered services</li>
+ * <li>{@link org.springframework.cloud.gateway.discovery.GatewayDiscoveryClientAutoConfiguration}
+ * - Auto-configuration for discovery client integration</li>
+ * </ul>
+ * </p>
+ *
+ * @see org.springframework.cloud.client.discovery.DiscoveryClient
+ * @see org.springframework.cloud.gateway.route.RouteDefinitionLocator
  */
 @NullMarked
 package org.springframework.cloud.gateway.discovery;
 
-import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullMarked;
\ No newline at end of file
diff --git a/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/event/package-info.java b/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/event/package-info.java
index fe5c006f88..092e99cad5 100644
--- a/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/event/package-info.java
+++ b/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/event/package-info.java
@@ -15,9 +15,33 @@
  */
 
 /**
- * TODO: package javadoc.
+ * Event publishing and handling for Spring Cloud Gateway.
+ *
+ * <p>
+ * This package provides event-driven capabilities for gateway lifecycle and route
+ * management. It enables applications to react to gateway events such as route
+ * refreshes, route definitions being added or removed, and other gateway state changes.
+ * </p>
+ *
+ * <p>
+ * Key components:
+ * <ul>
+ * <li>Event classes for various gateway lifecycle events</li>
+ * <li>Event publishers for notifying listeners of gateway state changes</li>
+ * <li>Integration with Spring's event publishing mechanism</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * Applications can listen to these events by implementing
+ * {@link org.springframework.context.ApplicationListener} or using the
+ * {@link org.springframework.context.event.EventListener} annotation.
+ * </p>
+ *
+ * @see org.springframework.context.ApplicationEvent
+ * @see org.springframework.context.ApplicationListener
  */
 @NullMarked
 package org.springframework.cloud.gateway.event;
 
-import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullMarked;
\ No newline at end of file
diff --git a/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/filter/package-info.java b/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/filter/package-info.java
index f89e5daf63..50c0e092bf 100644
--- a/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/filter/package-info.java
+++ b/spring-cloud-gateway-server-webflux/src/main/java/org/springframework/cloud/gateway/filter/package-info.java
@@ -9,15 +9,46 @@
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * WITHOUT WARRANTIES or conditions of ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 /**
- * TODO: package javadoc.
+ * Gateway filters for request and response processing.
+ *
+ * <p>
+ * This package contains the core filter implementations for Spring Cloud Gateway.
+ * Filters are used to modify incoming requests and outgoing responses as they pass
+ * through the gateway. They can be applied globally or scoped to specific routes.
+ * </p>
+ *
+ * <p>
+ * Filter types include:
+ * <ul>
+ * <li><strong>Global Filters:</strong> Applied to all routes</li>
+ * <li><strong>route Filters:</strong> Applied to specific routes</li>
+ * <li><strong>Pre-filters:</strong> Execute before the request is routed</li>
+ * <li><strong>Post-filters:</strong> Execute after the response is received</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * Common filter implementations:
+ * <ul>
+ * <li>{@link org.springframework.cloud.gateway.filter.NettyRoutingFilter}
+ * - Routes requests using Netty HTTP client</li>
+ * <li>{@link org.springframework.cloud.gateway.filter.ForwardRoutingFilter}
+ * - Forwards requests to local endpoints</li>
+ * <li>{@link org.springframework.cloud.gateway.filter.FunctionRoutingFilter}
+ * - Routes requests to Spring Cloud Function endpoints</li>
+ * </ul>
+ * </p>
+ *
+ * @see org.springframework.cloud.gateway.filter.GatewayFilter
+ * @see org.springframework.cloud.gateway.filter.GlobalFilter
  */
 @NullMarked
 package org.springframework.cloud.gateway.filter;
 
-import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullMarked;
\ No newline at end of file