Add JavaDoc with Example Usage to classes and non-private methods

microsphere-spring-cloud-commons/src/main/java/io/microsphere/spring/cloud/client/discovery/ReactiveDiscoveryClientAdapter.java

@@ -39,32 +39,67 @@ public class ReactiveDiscoveryClientAdapter implements DiscoveryClient {
 
     private final ReactiveDiscoveryClient reactiveDiscoveryClient;
 
+    /**
+     * Create a new {@link ReactiveDiscoveryClientAdapter} that wraps the given
+     * {@link ReactiveDiscoveryClient} as a blocking {@link DiscoveryClient}.
+     *
+     * <p>Example Usage:
+     * <pre>{@code
+     * ReactiveDiscoveryClient reactiveClient = new SimpleReactiveDiscoveryClient(properties);
+     * DiscoveryClient adapter = new ReactiveDiscoveryClientAdapter(reactiveClient);
+     * List<String> services = adapter.getServices();
+     * }</pre>
+     *
+     * @param reactiveDiscoveryClient the {@link ReactiveDiscoveryClient} to adapt, must not be {@code null}
+     */
     public ReactiveDiscoveryClientAdapter(ReactiveDiscoveryClient reactiveDiscoveryClient) {
         this.reactiveDiscoveryClient = reactiveDiscoveryClient;
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>Delegates to the underlying {@link ReactiveDiscoveryClient#description()}.
+     */
     @Override
     public String description() {
         return this.reactiveDiscoveryClient.description();
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>Delegates to {@link ReactiveDiscoveryClient#getInstances(String)} and collects the
+     * reactive {@link Flux} result into a blocking {@link List}.
+     */
     @Override
     public List<ServiceInstance> getInstances(String serviceId) {
         Flux<ServiceInstance> flux = this.reactiveDiscoveryClient.getInstances(serviceId);
         return toList(flux);
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>Delegates to {@link ReactiveDiscoveryClient#getServices()} and collects the
+     * reactive {@link Flux} result into a blocking {@link List}.
+     */
     @Override
     public List<String> getServices() {
         Flux<String> flux = this.reactiveDiscoveryClient.getServices();
         return toList(flux);
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>Delegates to {@link ReactiveDiscoveryClient#probe()}.
+     */
     @Override
     public void probe() {
         this.reactiveDiscoveryClient.probe();
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>Delegates to {@link ReactiveDiscoveryClient#getOrder()}.
+     */
     @Override
     public int getOrder() {
         return this.reactiveDiscoveryClient.getOrder();

microsphere-spring-cloud-commons/src/main/java/io/microsphere/spring/cloud/client/discovery/UnionDiscoveryClient.java

@@ -48,11 +48,20 @@ public final class UnionDiscoveryClient implements DiscoveryClient, ApplicationC
 
     private List<DiscoveryClient> discoveryClients;
 
+    /**
+     * {@inheritDoc}
+     *
+     * @return the description "Union Discovery Client"
+     */
     @Override
     public String description() {
         return "Union Discovery Client";
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>Aggregates service instances from all underlying {@link DiscoveryClient DiscoveryClients}.
+     */
     @Override
     public List<ServiceInstance> getInstances(String serviceId) {
         List<ServiceInstance> serviceInstances = new LinkedList<>();
@@ -66,6 +75,10 @@ public List<ServiceInstance> getInstances(String serviceId) {
         return serviceInstances;
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>Returns a deduplicated union of service names from all underlying {@link DiscoveryClient DiscoveryClients}.
+     */
     @Override
     public List<String> getServices() {
         LinkedHashSet<String> services = new LinkedHashSet<>();
@@ -79,6 +92,20 @@ public List<String> getServices() {
         return new ArrayList<>(services);
     }
 
+    /**
+     * Returns the sorted list of underlying {@link DiscoveryClient DiscoveryClients}, excluding
+     * {@link CompositeDiscoveryClient} and this instance itself. The list is lazily initialized
+     * from the {@link ApplicationContext} on first access and cached for subsequent calls.
+     *
+     * <p>Example Usage:
+     * <pre>{@code
+     * UnionDiscoveryClient unionClient = applicationContext.getBean(UnionDiscoveryClient.class);
+     * List<DiscoveryClient> clients = unionClient.getDiscoveryClients();
+     * clients.forEach(c -> System.out.println(c.description()));
+     * }</pre>
+     *
+     * @return an unmodifiable list of {@link DiscoveryClient} instances
+     */
     public List<DiscoveryClient> getDiscoveryClients() {
         List<DiscoveryClient> discoveryClients = this.discoveryClients;
         if (discoveryClients != null) {
@@ -98,21 +125,38 @@ public List<DiscoveryClient> getDiscoveryClients() {
         return discoveryClients;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @return {@link #HIGHEST_PRECEDENCE} to ensure this client takes priority
+     */
     @Override
     public int getOrder() {
         return HIGHEST_PRECEDENCE;
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>Eagerly initializes the list of {@link DiscoveryClient DiscoveryClients} after all singletons are instantiated.
+     */
     @Override
     public void afterSingletonsInstantiated() {
         this.discoveryClients = getDiscoveryClients();
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>Clears the cached list of {@link DiscoveryClient DiscoveryClients} on bean destruction.
+     */
     @Override
     public void destroy() throws Exception {
         this.discoveryClients.clear();
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>Stores the {@link ApplicationContext} used to look up {@link DiscoveryClient} beans.
+     */
     @Override
     public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
         this.context = applicationContext;

microsphere-spring-cloud-commons/src/main/java/io/microsphere/spring/cloud/client/discovery/autoconfigure/DiscoveryClientAutoConfiguration.java

@@ -80,6 +80,19 @@ public class DiscoveryClientAutoConfiguration {
     @ConditionalOnProperty(name = DISCOVERY_CLIENT_MODE_PROPERTY_NAME, havingValue = UNION_DISCOVERY_CLIENT_MODE)
     public static class UnionConfiguration {
 
+        /**
+         * Creates a {@link UnionDiscoveryClient} bean that aggregates all {@link DiscoveryClient}
+         * instances in the {@link org.springframework.context.ApplicationContext}.
+         *
+         * <p>Example Usage:
+         * <pre>{@code
+         * // Activated when microsphere.spring.cloud.client.discovery.mode=union
+         * UnionDiscoveryClient client = applicationContext.getBean(UnionDiscoveryClient.class);
+         * List<String> services = client.getServices();
+         * }</pre>
+         *
+         * @return a new {@link UnionDiscoveryClient} instance
+         */
         @Bean
         public UnionDiscoveryClient unionDiscoveryClient() {
             return new UnionDiscoveryClient();

microsphere-spring-cloud-commons/src/main/java/io/microsphere/spring/cloud/client/discovery/autoconfigure/ReactiveDiscoveryClientAutoConfiguration.java

@@ -61,6 +61,20 @@ public class ReactiveDiscoveryClientAutoConfiguration {
     @ConditionalOnBlockingDiscoveryEnabled
     public static class BlockingConfiguration {
 
+        /**
+         * Creates a {@link ReactiveDiscoveryClientAdapter} bean that adapts a
+         * {@link ReactiveDiscoveryClient} to the blocking {@link org.springframework.cloud.client.discovery.DiscoveryClient} interface.
+         *
+         * <p>Example Usage:
+         * <pre>{@code
+         * // Auto-configured when both reactive and blocking discovery are enabled
+         * DiscoveryClient client = applicationContext.getBean(ReactiveDiscoveryClientAdapter.class);
+         * List<String> services = client.getServices();
+         * }</pre>
+         *
+         * @param reactiveDiscoveryClient the {@link ReactiveDiscoveryClient} to adapt
+         * @return a new {@link ReactiveDiscoveryClientAdapter} instance
+         */
         @Bean
         @ConditionalOnBean(ReactiveDiscoveryClient.class)
         public ReactiveDiscoveryClientAdapter reactiveDiscoveryClientAdapter(ReactiveDiscoveryClient reactiveDiscoveryClient) {

microsphere-spring-cloud-commons/src/main/java/io/microsphere/spring/cloud/client/service/registry/InMemoryServiceRegistry.java

@@ -35,23 +35,73 @@ public class InMemoryServiceRegistry implements ServiceRegistry {
 
     private final ConcurrentMap<String, Registration> storage = new ConcurrentHashMap<>(1);
 
+    /**
+     * Registers the given {@link Registration} instance in the in-memory storage,
+     * keyed by its instance ID.
+     *
+     * <p>Example Usage:
+     * <pre>{@code
+     * InMemoryServiceRegistry registry = new InMemoryServiceRegistry();
+     * Registration registration = createRegistration();
+     * registry.register(registration);
+     * }</pre>
+     *
+     * @param registration the {@link Registration} to store
+     */
     @Override
     public void register(Registration registration) {
         String id = registration.getInstanceId();
         storage.put(id, registration);
     }
 
+    /**
+     * Removes the given {@link Registration} instance from the in-memory storage.
+     *
+     * <p>Example Usage:
+     * <pre>{@code
+     * InMemoryServiceRegistry registry = new InMemoryServiceRegistry();
+     * Registration registration = createRegistration();
+     * registry.register(registration);
+     * registry.deregister(registration);
+     * }</pre>
+     *
+     * @param registration the {@link Registration} to remove
+     */
     @Override
     public void deregister(Registration registration) {
         String id = registration.getInstanceId();
         storage.remove(id, registration);
     }
 
+    /**
+     * Closes this registry by clearing all stored {@link Registration} instances.
+     *
+     * <p>Example Usage:
+     * <pre>{@code
+     * InMemoryServiceRegistry registry = new InMemoryServiceRegistry();
+     * registry.register(registration);
+     * registry.close();
+     * }</pre>
+     */
     @Override
     public void close() {
         storage.clear();
     }
 
+    /**
+     * Sets the status of the given {@link Registration} by storing it in
+     * the registration's metadata under the {@code _status_} key.
+     *
+     * <p>Example Usage:
+     * <pre>{@code
+     * InMemoryServiceRegistry registry = new InMemoryServiceRegistry();
+     * registry.register(registration);
+     * registry.setStatus(registration, "UP");
+     * }</pre>
+     *
+     * @param registration the {@link Registration} whose status is to be set
+     * @param status       the status value to set
+     */
     @Override
     public void setStatus(Registration registration, String status) {
         Map<String, String> metadata = getMetadata(registration);
@@ -60,6 +110,20 @@ public void setStatus(Registration registration, String status) {
         }
     }
 
+    /**
+     * Retrieves the status of the given {@link Registration} from its metadata.
+     *
+     * <p>Example Usage:
+     * <pre>{@code
+     * InMemoryServiceRegistry registry = new InMemoryServiceRegistry();
+     * registry.register(registration);
+     * registry.setStatus(registration, "UP");
+     * Object status = registry.getStatus(registration); // "UP"
+     * }</pre>
+     *
+     * @param registration the {@link Registration} whose status is to be retrieved
+     * @return the status value, or {@code null} if not set or registration not found
+     */
     @Override
     public Object getStatus(Registration registration) {
         Map<String, String> metadata = getMetadata(registration);
@@ -69,6 +133,20 @@ public Object getStatus(Registration registration) {
         return null;
     }
 
+    /**
+     * Retrieves the metadata {@link Map} for the given {@link Registration}
+     * from the in-memory storage.
+     *
+     * <p>Example Usage:
+     * <pre>{@code
+     * InMemoryServiceRegistry registry = new InMemoryServiceRegistry();
+     * registry.register(registration);
+     * Map<String, String> metadata = registry.getMetadata(registration);
+     * }</pre>
+     *
+     * @param registration the {@link Registration} whose metadata is to be retrieved
+     * @return the metadata map, or {@code null} if the registration is not found
+     */
     protected Map<String, String> getMetadata(Registration registration) {
         String id = registration.getInstanceId();
         Registration instance = storage.get(id);