2.x: improve autoConnect() Javadoc + add its marble (#5756)

Author: akarnokd

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

@@ -78,19 +78,45 @@ public Flowable<T> refCount() {
     }
 
     /**
-     * Returns a Flowable that automatically connects to this ConnectableFlowable
+     * Returns a Flowable that automatically connects (at most once) to this ConnectableFlowable
      * when the first 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
+     * 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.
+     * <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.
      *
      * @return a Flowable that automatically connects to this ConnectableFlowable
      *         when the first Subscriber subscribes
+     * @see #refCount()
+     * @see #autoConnect(int, Consumer)
      */
     @NonNull
     public Flowable<T> autoConnect() {
         return autoConnect(1);
     }
     /**
-     * Returns a Flowable that automatically connects to this ConnectableFlowable
+     * Returns a Flowable that automatically connects (at most once) to this ConnectableFlowable
      * when the specified number of Subscribers 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
+     * 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.
+     * <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.
      *
      * @param numberOfSubscribers the number of subscribers to await before calling connect
      *                            on the ConnectableFlowable. A non-positive value indicates
@@ -104,9 +130,17 @@ public Flowable<T> autoConnect(int numberOfSubscribers) {
     }
 
     /**
-     * Returns a Flowable that automatically connects to this ConnectableFlowable
+     * 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.
+     * <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
+     * 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.
      *
      * @param numberOfSubscribers the number of subscribers to await before calling connect
      *                            on the ConnectableFlowable. A non-positive value indicates

src/main/java/io/reactivex/observables/ConnectableObservable.java

@@ -77,8 +77,20 @@ public Observable<T> refCount() {
     }
 
     /**
-     * Returns an Observable that automatically connects to this ConnectableObservable
+     * Returns an Observable that automatically connects (at most once) to this ConnectableObservable
      * when the first Observer subscribes.
+     * <p>
+     * <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.o.png" alt="">
+     * <p>
+     * The connection happens after the first subscription and happens at most once
+     * during the lifetime of the returned Observable. If this ConnectableObservable
+     * terminates, the connection is never renewed, no matter how Observers come
+     * and go. Use {@link #refCount()} to renew a connection or dispose an active
+     * connection when all {@code Observers}s have disposed their {@code Disposable}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.
      *
      * @return an Observable that automatically connects to this ConnectableObservable
      *         when the first Observer subscribes
@@ -89,8 +101,20 @@ public Observable<T> autoConnect() {
     }
 
     /**
-     * Returns an Observable that automatically connects to this ConnectableObservable
+     * Returns an Observable that automatically connects (at most once) to this ConnectableObservable
      * when the specified number of Observers subscribe to it.
+     * <p>
+     * <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.o.png" alt="">
+     * <p>
+     * The connection happens after the given number of subscriptions and happens at most once
+     * during the lifetime of the returned Observable. If this ConnectableObservable
+     * terminates, the connection is never renewed, no matter how Observers come
+     * and go. Use {@link #refCount()} to renew a connection or dispose an active
+     * connection when all {@code Observers}s have disposed their {@code Disposable}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.
      *
      * @param numberOfSubscribers the number of subscribers to await before calling connect
      *                            on the ConnectableObservable. A non-positive value indicates
@@ -104,9 +128,17 @@ public Observable<T> autoConnect(int numberOfSubscribers) {
     }
 
     /**
-     * Returns an Observable that automatically connects to this ConnectableObservable
+     * Returns an Observable that automatically connects (at most once) to this ConnectableObservable
      * when the specified number of Subscribers subscribe to it and calls the
      * specified callback with the Subscription associated with the established connection.
+     * <p>
+     * <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.o.png" alt="">
+     * <p>
+     * The connection happens after the given number of subscriptions and happens at most once
+     * during the lifetime of the returned Observable. If this ConnectableObservable
+     * terminates, the connection is never renewed, no matter how Observers come
+     * and go. Use {@link #refCount()} to renew a connection or dispose an active
+     * connection when all {@code Observers}s have disposed their {@code Disposable}s.
      *
      * @param numberOfSubscribers the number of subscribers to await before calling connect
      *                            on the ConnectableObservable. A non-positive value indicates