3.x: JavaDocs: clarify create emitters are per consumer (#6535)

Author: akarnokd

src/main/java/io/reactivex/Completable.java

@@ -292,6 +292,12 @@ public static Completable concat(Publisher<? extends CompletableSource> sources,
      *
      * });
      * </code></pre>
+     * <p>
+     * Whenever a {@link CompletableObserver} subscribes to the returned {@code Completable}, the provided
+     * {@link CompletableOnSubscribe} callback is invoked with a fresh instance of a {@link CompletableEmitter}
+     * that will interact only with that specific {@code CompletableObserver}. If this {@code CompletableObserver}
+     * disposes the flow (making {@link CompletableEmitter#isDisposed} return true),
+     * other observers subscribed to the same returned {@code Completable} are not affected.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code create} does not operate by default on a particular {@link Scheduler}.</dd>

src/main/java/io/reactivex/Flowable.java

@@ -1877,6 +1877,12 @@ public static <T> Flowable<T> concatEager(Iterable<? extends Publisher<? extends
      * }, BackpressureStrategy.BUFFER);
      * </code></pre>
      * <p>
+     * Whenever a {@link Subscriber} subscribes to the returned {@code Flowable}, the provided
+     * {@link FlowableOnSubscribe} callback is invoked with a fresh instance of a {@link FlowableEmitter}
+     * that will interact only with that specific {@code Subscriber}. If this {@code Subscriber}
+     * cancels the flow (making {@link FlowableEmitter#isCancelled} return true),
+     * other observers subscribed to the same returned {@code Flowable} are not affected.
+     * <p>
      * You should call the FlowableEmitter onNext, onError and onComplete methods in a serialized fashion. The
      * rest of its methods are thread-safe.
      * <dl>

src/main/java/io/reactivex/Maybe.java

@@ -554,6 +554,12 @@ public static <T> Flowable<T> concatEager(Publisher<? extends MaybeSource<? exte
      *
      * });
      * </code></pre>
+     * <p>
+     * Whenever a {@link MaybeObserver} subscribes to the returned {@code Maybe}, the provided
+     * {@link MaybeOnSubscribe} callback is invoked with a fresh instance of a {@link MaybeEmitter}
+     * that will interact only with that specific {@code MaybeObserver}. If this {@code MaybeObserver}
+     * disposes the flow (making {@link MaybeEmitter#isDisposed} return true),
+     * other observers subscribed to the same returned {@code Maybe} are not affected.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code create} does not operate by default on a particular {@link Scheduler}.</dd>

src/main/java/io/reactivex/Observable.java

@@ -1611,6 +1611,12 @@ public static <T> Observable<T> concatEager(Iterable<? extends ObservableSource<
      * });
      * </code></pre>
      * <p>
+     * Whenever an {@link Observer} subscribes to the returned {@code Observable}, the provided
+     * {@link ObservableOnSubscribe} callback is invoked with a fresh instance of an {@link ObservableEmitter}
+     * that will interact only with that specific {@code Observer}. If this {@code Observer}
+     * disposes the flow (making {@link ObservableEmitter#isDisposed} return true),
+     * other observers subscribed to the same returned {@code Observable} are not affected.
+     * <p>
      * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/create.png" alt="">
      * <p>
      * You should call the ObservableEmitter's onNext, onError and onComplete methods in a serialized fashion. The

src/main/java/io/reactivex/Single.java

@@ -501,6 +501,12 @@ public static <T> Flowable<T> concatEager(Iterable<? extends SingleSource<? exte
      *
      * });
      * </code></pre>
+     * <p>
+     * Whenever a {@link SingleObserver} subscribes to the returned {@code Single}, the provided
+     * {@link SingleOnSubscribe} callback is invoked with a fresh instance of a {@link SingleEmitter}
+     * that will interact only with that specific {@code SingleObserver}. If this {@code SingleObserver}
+     * disposes the flow (making {@link SingleEmitter#isDisposed} return true),
+     * other observers subscribed to the same returned {@code Single} are not affected.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code create} does not operate by default on a particular {@link Scheduler}.</dd>