3.x: Improve Javadocs of Connectable sources (#7127)

Author: akarnokd

src/main/java/io/reactivex/rxjava3/flowables/ConnectableFlowable.java

@@ -16,7 +16,7 @@
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 
-import org.reactivestreams.Subscriber;
+import org.reactivestreams.*;
 
 import io.reactivex.rxjava3.annotations.*;
 import io.reactivex.rxjava3.core.*;
@@ -37,9 +37,9 @@
  * <img width="640" height="510" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/publishConnect.v3.png" alt="">
  * <p>
  * When the upstream terminates, the {@code ConnectableFlowable} remains in this terminated state and,
- * depending on the actual underlying implementation, relays cached events to late {@link Subscriber}s.
+ * depending on the actual underlying implementation, relays cached events to late {@code Subscriber}s.
  * In order to reuse and restart this {@code ConnectableFlowable}, the {@link #reset()} method has to be called.
- * When called, this {@code ConnectableFlowable} will appear as fresh, unconnected source to new {@link Subscriber}s.
+ * When called, this {@code ConnectableFlowable} will appear as fresh, unconnected source to new {@code Subscriber}s.
  * Disposing the connection will reset the {@code ConnectableFlowable} to its fresh state and there is no need to call
  * {@code reset()} in this case.
  * <p>
@@ -48,8 +48,7 @@
  * there is no unwanted signal loss due to early {@code connect()} or {@code reset()} calls while {@code Subscriber}s are
  * still being subscribed to to this {@code ConnectableFlowable} to receive signals from the get go.
  * <p>
- * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Connectable-Observable-Operators">RxJava Wiki:
- *      Connectable Observable Operators</a>
+ * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Connectable-Observable-Operators">RxJava Wiki: Connectable Observable Operators</a>
  * @param <T>
  *          the type of items emitted by the {@code ConnectableFlowable}
  * @since 2.0.0
@@ -74,7 +73,7 @@ public abstract class ConnectableFlowable<T> extends Flowable<T> {
     public abstract void connect(@NonNull Consumer<? super Disposable> connection);
 
     /**
-     * Resets this ConnectableFlowable into its fresh state if it has terminated.
+     * Resets this {@code ConnectableFlowable} into its fresh state if it has terminated.
      * <p>
      * Calling this method on a fresh or active {@code ConnectableFlowable} has no effect.
      * <dl>
@@ -108,7 +107,7 @@ public final Disposable connect() {
     }
 
     /**
-     * Returns a {@code Flowable} that stays connected to this {@code ConnectableFlowable} as long as there
+     * Returns a {@link Flowable} that stays connected to this {@code ConnectableFlowable} as long as there
      * is at least one subscription to this {@code ConnectableFlowable}.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -117,7 +116,7 @@ public final Disposable connect() {
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>This {@code refCount} overload does not operate on any particular {@link Scheduler}.</dd>
      * </dl>
-     * @return a {@link Flowable}
+     * @return the new {@code Flowable} instance
      * @see <a href="http://reactivex.io/documentation/operators/refcount.html">ReactiveX documentation: RefCount</a>
      * @see #refCount(int)
      * @see #refCount(long, TimeUnit)
@@ -143,7 +142,8 @@ public Flowable<T> refCount() {
      * </dl>
      * <p>History: 2.1.14 - experimental
      * @param subscriberCount the number of subscribers required to connect to the upstream
-     * @return the new Flowable instance
+     * @return the new {@link Flowable} instance
+     * @throws IllegalArgumentException if {@code subscriberCount} is non-positive
      * @since 2.2
      */
     @CheckReturnValue
@@ -168,7 +168,7 @@ public final Flowable<T> refCount(int subscriberCount) {
      * <p>History: 2.1.14 - experimental
      * @param timeout the time to wait before disconnecting after all subscribers unsubscribed
      * @param unit the time unit of the timeout
-     * @return the new Flowable instance
+     * @return the new {@link Flowable} instance
      * @throws NullPointerException if {@code unit} is {@code null}
      * @see #refCount(long, TimeUnit, Scheduler)
      * @since 2.2
@@ -196,7 +196,7 @@ public final Flowable<T> refCount(long timeout, @NonNull TimeUnit unit) {
      * @param timeout the time to wait before disconnecting after all subscribers unsubscribed
      * @param unit the time unit of the timeout
      * @param scheduler the target scheduler to wait on before disconnecting
-     * @return the new Flowable instance
+     * @return the new {@link Flowable} instance
      * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
      * @since 2.2
      */
@@ -223,8 +223,9 @@ public final Flowable<T> refCount(long timeout, @NonNull TimeUnit unit, @NonNull
      * @param subscriberCount the number of subscribers required to connect to the upstream
      * @param timeout the time to wait before disconnecting after all subscribers unsubscribed
      * @param unit the time unit of the timeout
-     * @return the new Flowable instance
+     * @return the new {@link Flowable} instance
      * @throws NullPointerException if {@code unit} is {@code null}
+     * @throws IllegalArgumentException if {@code subscriberCount} is non-positive
      * @see #refCount(int, long, TimeUnit, Scheduler)
      * @since 2.2
      */
@@ -252,7 +253,7 @@ public final Flowable<T> refCount(int subscriberCount, long timeout, @NonNull Ti
      * @param timeout the time to wait before disconnecting after all subscribers unsubscribed
      * @param unit the time unit of the timeout
      * @param scheduler the target scheduler to wait on before disconnecting
-     * @return the new Flowable instance
+     * @return the new {@link Flowable} instance
      * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
      * @throws IllegalArgumentException if {@code subscriberCount} is non-positive
      * @since 2.2
@@ -269,20 +270,20 @@ public final Flowable<T> refCount(int subscriberCount, long timeout, @NonNull Ti
     }
 
     /**
-     * Returns a Flowable that automatically connects (at most once) to this ConnectableFlowable
-     * when the first Subscriber subscribes.
+     * Returns a {@link Flowable} that automatically connects (at most once) to this {@code ConnectableFlowable}
+     * when the first {@link Subscriber} subscribes.
      * <p>
      * <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.f.png" alt="">
      * <p>
      * The connection happens after the first subscription and happens at most once
-     * during the lifetime of the returned Flowable. If this ConnectableFlowable
-     * terminates, the connection is never renewed, no matter how Subscribers come
+     * during the lifetime of the returned {@code Flowable}. If this {@code ConnectableFlowable}
+     * terminates, the connection is never renewed, no matter how {@code Subscriber}s come
      * and go. Use {@link #refCount()} to renew a connection or dispose an active
-     * connection when all {@code Subscriber}s have cancelled their {@code Subscription}s.
+     * connection when all {@code Subscriber}s have cancelled their {@link Subscription}s.
      * <p>
      * This overload does not allow disconnecting the connection established via
      * {@link #connect(Consumer)}. Use the {@link #autoConnect(int, Consumer)} overload
-     * to gain access to the {@code Disposable} representing the only connection.
+     * to gain access to the {@link Disposable} representing the only connection.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator itself doesn't interfere with backpressure which is determined by
@@ -291,8 +292,8 @@ public final Flowable<T> refCount(int subscriberCount, long timeout, @NonNull Ti
      *  <dd>{@code autoConnect} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
      *
-     * @return a Flowable that automatically connects to this ConnectableFlowable
-     *         when the first Subscriber subscribes
+     * @return a new {@code Flowable} instance that automatically connects to this {@code ConnectableFlowable}
+     *         when the first {@code Subscriber} subscribes
      * @see #refCount()
      * @see #autoConnect(int, Consumer)
      */
@@ -304,20 +305,20 @@ public Flowable<T> autoConnect() {
         return autoConnect(1);
     }
     /**
-     * Returns a Flowable that automatically connects (at most once) to this ConnectableFlowable
-     * when the specified number of Subscribers subscribe to it.
+     * Returns a {@link Flowable} that automatically connects (at most once) to this {@code ConnectableFlowable}
+     * when the specified number of {@link Subscriber}s subscribe to it.
      * <p>
      * <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.f.png" alt="">
      * <p>
      * The connection happens after the given number of subscriptions and happens at most once
-     * during the lifetime of the returned Flowable. If this ConnectableFlowable
-     * terminates, the connection is never renewed, no matter how Subscribers come
+     * during the lifetime of the returned {@code Flowable}. If this {@code ConnectableFlowable}
+     * terminates, the connection is never renewed, no matter how {@code Subscriber}s come
      * and go. Use {@link #refCount()} to renew a connection or dispose an active
-     * connection when all {@code Subscriber}s have cancelled their {@code Subscription}s.
+     * connection when all {@code Subscriber}s have cancelled their {@link Subscription}s.
      * <p>
      * This overload does not allow disconnecting the connection established via
      * {@link #connect(Consumer)}. Use the {@link #autoConnect(int, Consumer)} overload
-     * to gain access to the {@code Disposable} representing the only connection.
+     * to gain access to the {@link Disposable} representing the only connection.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator itself doesn't interfere with backpressure which is determined by
@@ -327,10 +328,10 @@ public Flowable<T> autoConnect() {
      * </dl>
      *
      * @param numberOfSubscribers the number of subscribers to await before calling connect
-     *                            on the ConnectableFlowable. A non-positive value indicates
+     *                            on the {@code ConnectableFlowable}. A non-positive value indicates
      *                            an immediate connection.
-     * @return a Flowable that automatically connects to this ConnectableFlowable
-     *         when the specified number of Subscribers subscribe to it
+     * @return a new {@code Flowable} instance that automatically connects to this {@code ConnectableFlowable}
+     *         when the specified number of {@code Subscriber}s subscribe to it
      */
     @NonNull
     @CheckReturnValue
@@ -341,17 +342,17 @@ public Flowable<T> autoConnect(int numberOfSubscribers) {
     }
 
     /**
-     * Returns a Flowable that automatically connects (at most once) to this ConnectableFlowable
-     * when the specified number of Subscribers subscribe to it and calls the
-     * specified callback with the Subscription associated with the established connection.
+     * Returns a {@link Flowable} that automatically connects (at most once) to this {@code ConnectableFlowable}
+     * when the specified number of {@link Subscriber}s subscribe to it and calls the
+     * specified callback with the {@link Disposable} associated with the established connection.
      * <p>
      * <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.f.png" alt="">
      * <p>
      * The connection happens after the given number of subscriptions and happens at most once
-     * during the lifetime of the returned Flowable. If this ConnectableFlowable
-     * terminates, the connection is never renewed, no matter how Subscribers come
+     * during the lifetime of the returned {@code Flowable}. If this {@code ConnectableFlowable}
+     * terminates, the connection is never renewed, no matter how {@code Subscriber}s come
      * and go. Use {@link #refCount()} to renew a connection or dispose an active
-     * connection when all {@code Subscriber}s have cancelled their {@code Subscription}s.
+     * connection when all {@code Subscriber}s have cancelled their {@link Subscription}s.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator itself doesn't interfere with backpressure which is determined by
@@ -361,13 +362,13 @@ public Flowable<T> autoConnect(int numberOfSubscribers) {
      * </dl>
      *
      * @param numberOfSubscribers the number of subscribers to await before calling connect
-     *                            on the ConnectableFlowable. A non-positive value indicates
+     *                            on the {@code ConnectableFlowable}. A non-positive value indicates
      *                            an immediate connection.
-     * @param connection the callback Consumer that will receive the Subscription representing the
+     * @param connection the callback {@link Consumer} that will receive the {@code Disposable} representing the
      *                   established connection
-     * @return a Flowable that automatically connects to this ConnectableFlowable
-     *         when the specified number of Subscribers subscribe to it and calls the
-     *         specified callback with the Subscription associated with the established connection
+     * @return a new {@code Flowable} instance that automatically connects to this {@code ConnectableFlowable}
+     *         when the specified number of {@code Subscriber}s subscribe to it and calls the
+     *         specified callback with the {@code Disposable} associated with the established connection
      * @throws NullPointerException if {@code connection} is {@code null}
      */
     @NonNull