Add marble diagrams for various Single operators (#6141)

Author: UMFsimke

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

@@ -414,6 +414,8 @@ public static <T> Flowable<T> concatArrayEager(SingleSource<? extends T>... sour
     /**
      * Concatenates a Publisher sequence of SingleSources eagerly into a single stream of values.
      * <p>
+     * <img width="640" height="307" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatEager.p.png" alt="">
+     * <p>
      * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
      * emitted source Publishers as they are observed. The operator buffers the values emitted by these
      * Publishers and then drains them in order, each one after the previous one completes.
@@ -439,6 +441,8 @@ public static <T> Flowable<T> concatEager(Publisher<? extends SingleSource<? ext
     /**
      * Concatenates a sequence of SingleSources eagerly into a single stream of values.
      * <p>
+     * <img width="640" height="319" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatEager.i.png" alt="">
+     * <p>
      * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
      * source SingleSources. The operator buffers the values emitted by these SingleSources and then drains them
      * in order, each one after the previous one completes.
@@ -462,6 +466,8 @@ public static <T> Flowable<T> concatEager(Iterable<? extends SingleSource<? exte
     /**
      * Provides an API (via a cold Completable) that bridges the reactive world with the callback-style world.
      * <p>
+     * <img width="640" height="454" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.create.png" alt="">
+     * <p>
      * Example:
      * <pre><code>
      * Single.&lt;Event&gt;create(emitter -&gt; {
@@ -808,6 +814,8 @@ public static <T> Single<T> just(final T item) {
     /**
      * Merges an Iterable sequence of SingleSource instances into a single Flowable sequence,
      * running all SingleSources at once.
+     * <p>
+     * <img width="640" height="319" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.i.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
@@ -843,6 +851,8 @@ public static <T> Flowable<T> merge(Iterable<? extends SingleSource<? extends T>
     /**
      * Merges a Flowable sequence of SingleSource instances into a single Flowable sequence,
      * running all SingleSources at once.
+     * <p>
+     * <img width="640" height="307" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.p.png" alt="">
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
@@ -881,7 +891,7 @@ public static <T> Flowable<T> merge(Publisher<? extends SingleSource<? extends T
      * Flattens a {@code Single} that emits a {@code Single} into a single {@code Single} that emits the item
      * emitted by the nested {@code Single}, without any transformation.
      * <p>
-     * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.oo.png" alt="">
+     * <img width="640" height="412" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.oo.png" alt="">
      * <dl>
      * <dt><b>Scheduler:</b></dt>
      * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
@@ -910,7 +920,7 @@ public static <T> Single<T> merge(SingleSource<? extends SingleSource<? extends
     /**
      * Flattens two Singles into a single Flowable, without any transformation.
      * <p>
-     * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">
+     * <img width="640" height="414" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">
      * <p>
      * You can combine items emitted by multiple Singles so that they appear as a single Flowable, by
      * using the {@code merge} method.
@@ -958,7 +968,7 @@ public static <T> Flowable<T> merge(
     /**
      * Flattens three Singles into a single Flowable, without any transformation.
      * <p>
-     * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">
+     * <img width="640" height="366" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.o3.png" alt="">
      * <p>
      * You can combine items emitted by multiple Singles so that they appear as a single Flowable, by using
      * the {@code merge} method.
@@ -1010,7 +1020,7 @@ public static <T> Flowable<T> merge(
     /**
      * Flattens four Singles into a single Flowable, without any transformation.
      * <p>
-     * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">
+     * <img width="640" height="362" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.o4.png" alt="">
      * <p>
      * You can combine items emitted by multiple Singles so that they appear as a single Flowable, by using
      * the {@code merge} method.
@@ -1299,6 +1309,8 @@ public static Single<Long> timer(final long delay, final TimeUnit unit, final Sc
 
     /**
      * Compares two SingleSources and emits true if they emit the same value (compared via Object.equals).
+     * <p>
+     * <img width="640" height="465" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.equals.png" alt="">
      * <dl>
      * <dt><b>Scheduler:</b></dt>
      * <dd>{@code equals} does not operate by default on a particular {@link Scheduler}.</dd>
@@ -1913,6 +1925,8 @@ public static <T, R> Single<R> zipArray(Function<? super Object[], ? extends R>
 
     /**
      * Signals the event of this or the other SingleSource whichever signals first.
+     * <p>
+     * <img width="640" height="463" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.ambWith.png" alt="">
      * <dl>
      * <dt><b>Scheduler:</b></dt>
      * <dd>{@code ambWith} does not operate by default on a particular {@link Scheduler}.</dd>
@@ -1933,6 +1947,8 @@ public final Single<T> ambWith(SingleSource<? extends T> other) {
     /**
      * Calls the specified converter function during assembly time and returns its resulting value.
      * <p>
+     * <img width="640" height="553" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.as.png" alt="">
+     * <p>
      * This allows fluent conversion to any other type.
      * <dl>
      * <dt><b>Scheduler:</b></dt>
@@ -1972,6 +1988,8 @@ public final Single<T> hide() {
     /**
      * Transform a Single by applying a particular Transformer function to it.
      * <p>
+     * <img width="640" height="612" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.compose.png" alt="">
+     * <p>
      * This method operates on the Single itself whereas {@link #lift} operates on the Single's SingleObservers.
      * <p>
      * If the operator you are creating is designed to act on the individual item emitted by a Single, use
@@ -2281,7 +2299,10 @@ public final Single<T> delaySubscription(long time, TimeUnit unit, Scheduler sch
 
     /**
      * Calls the specified consumer with the success item after this item has been emitted to the downstream.
-     * <p>Note that the {@code doAfterSuccess} action is shared between subscriptions and as such
+     * <p>
+     * <img width="640" height="460" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doAfterSuccess.png" alt="">
+     * <p>
+     * Note that the {@code doAfterSuccess} action is shared between subscriptions and as such
      * should be thread-safe.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
@@ -2301,10 +2322,12 @@ public final Single<T> doAfterSuccess(Consumer<? super T> onAfterSuccess) {
 
     /**
      * Registers an {@link Action} to be called after this Single invokes either onSuccess or onError.
-     * * <p>Note that the {@code doAfterTerminate} action is shared between subscriptions and as such
-     * should be thread-safe.</p>
      * <p>
-     * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doAfterTerminate.png" alt="">
+     * <img width="640" height="460" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doAfterTerminate.png" alt="">
+     * <p>
+     * Note that the {@code doAfterTerminate} action is shared between subscriptions and as such
+     * should be thread-safe.</p>
+     *
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code doAfterTerminate} does not operate by default on a particular {@link Scheduler}.</dd>
@@ -2884,7 +2907,7 @@ public final Single<Boolean> contains(final Object value, final BiPredicate<Obje
     /**
      * Flattens this and another Single into a single Flowable, without any transformation.
      * <p>
-     * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">
+     * <img width="640" height="415" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.mergeWith.png" alt="">
      * <p>
      * You can combine items emitted by multiple Singles so that they appear as a single Flowable, by using
      * the {@code mergeWith} method.
@@ -3654,6 +3677,8 @@ private Single<T> timeout0(final long timeout, final TimeUnit unit, final Schedu
     /**
      * Calls the specified converter function with the current Single instance
      * during assembly time and returns its result.
+     * <p>
+     * <img width="640" height="553" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.to.png" alt="">
      * <dl>
      * <dt><b>Scheduler:</b></dt>
      * <dd>{@code to} does not operate by default on a particular {@link Scheduler}.</dd>