Enhance clarifications for ServiceDiscoverer contract

servicetalk-client-api/src/main/java/io/servicetalk/client/api/ServiceDiscoverer.java

@@ -15,6 +15,7 @@
  */
 package io.servicetalk.client.api;
 
+import io.servicetalk.concurrent.PublisherSource.Subscriber;
 import io.servicetalk.concurrent.PublisherSource.Subscription;
 import io.servicetalk.concurrent.api.ListenableAsyncCloseable;
 import io.servicetalk.concurrent.api.Publisher;
@@ -26,6 +27,12 @@
  * is called that the service discovery system will push data updates or implementations of this interface will poll for
  * data updates. Changes in the available addresses will be communicated via the resulting {@link Publisher}.
  * <p>
+ * Because typically a {@link ServiceDiscoverer} implementation runs in the background and doesn't require many compute
+ * resources, it's recommended (but not required) to run it and deliver updates on a single thread either for all
+ * discoveries or at least for all {@link Subscriber Subscribers} to the same {@link Publisher}. One possible advantage
+ * of a single-threaded model is that it will make debugging easier as discovery events and the logs they generate will
+ * be less susceptible to reordering.
+ * <p>
  * See {@link ServiceDiscovererEvent} for documentation regarding the interpretation of events.
  *
  * @param <UnresolvedAddress> The type of address before resolution.
@@ -39,8 +46,12 @@ public interface ServiceDiscoverer<UnresolvedAddress, ResolvedAddress,
      * {@code address}.
      * <p>
      * In general a call to this method will continue to discover changes related to {@code address} until the
-     * {@link Subscription} corresponding to the return value is cancelled via {@link Subscription#cancel()} or there
-     * are no more changes to be published.
+     * {@link Subscription Subscription} corresponding to the return value is {@link Subscription#cancel() cancelled} or
+     * {@link Publisher} fails with an error. The returned {@link Publisher} should never
+     * {@link Subscriber#onComplete() complete} because underlying system may run for a long period of time and updates
+     * may be required at any time in the future. The returned {@link Publisher} MUST support re-subscribes to allow
+     * underlying systems retry failures or re-subscribe after {@link Subscription#cancel() cancellation}.
+     *
      * @param address the service address to discover. Examples of what this address maybe are:
      * <ul>
      * <li>hostname/port (e.g. InetAddress)</li>

servicetalk-client-api/src/main/java/io/servicetalk/client/api/ServiceDiscovererEvent.java

@@ -15,23 +15,27 @@
  */
 package io.servicetalk.client.api;
 
+import io.servicetalk.concurrent.PublisherSource.Subscriber;
+
 import java.util.Locale;
 
 /**
  * Notification from the Service Discovery system that availability for an address has changed.
  * <p>
  * Interpreting Events
- * <ul>
- *     <li>When subscribing (or re-subscribing to recovery from faults) to an event stream the initial collection of
+ * <ol>
+ *     <li>When subscribing (or re-subscribing to recover from failures) to an event stream the initial collection of
  *         events is considered to be the current state of the world.</li>
  *     <li>Each event represents the current state of the {@link ResolvedAddress} overriding any previously known
  *         {@link Status} and any associated meta-data.</li>
- * </ul>
- * <p>
- * Example
+ * </ol>
+ * Item 1 is required to satisfy
+ * <a href="https://github.com/reactive-streams/reactive-streams-jvm?tab=readme-ov-file#1.10">
+ * Reactive Streams Rule 1.10</a>, which requires every subscribe to happen with a new {@link Subscriber Subscriber}.
+ * As a result, {@link Subscriber Subscriber} needs to know the initial state to start from.
  * <p>
- * We can represent a {@link ServiceDiscovererEvent} as map entries of the form
- * ({@link ResolvedAddress}, ({@link Status}, meta-data)) where the {@link ResolvedAddress} is the map key.
+ * Item 2 can be clarified by the following example: we can represent a {@link ServiceDiscovererEvent} as map entries of
+ * the form ({@link ResolvedAddress}, ({@link Status}, meta-data)) where the {@link ResolvedAddress} is the map key.
  * <pre>
  * Starting with the initial state of {addr1, (AVAILABLE, meta-1)}. Upon subscribing to the event stream the initial
  * state is populated via the event (addr1, (AVAILABLE, meta-1)).