2.x: Improve Javadocs of flatMapSingle and flatMapMaybe (#5709)

Author: akarnokd

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

@@ -8945,8 +8945,8 @@ public final <U, V> Flowable<V> flatMapIterable(final Function<? super T, ? exte
     }
 
     /**
-     * Maps each element of the upstream Flowable into MaybeSources, subscribes to them and
-     * waits until the upstream and all MaybeSources complete.
+     * Maps each element of the upstream Flowable into MaybeSources, subscribes to all of them
+     * and merges their onSuccess values, in no particular order, into a single Flowable sequence.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator consumes the upstream in an unbounded manner.</dd>
@@ -8965,8 +8965,9 @@ public final <R> Flowable<R> flatMapMaybe(Function<? super T, ? extends MaybeSou
     }
 
     /**
-     * Maps each element of the upstream Flowable into MaybeSources, subscribes to them and
-     * waits until the upstream and all MaybeSources complete, optionally delaying all errors.
+     * Maps each element of the upstream Flowable into MaybeSources, subscribes to at most
+     * {@code maxConcurrency} MaybeSources at a time and merges their onSuccess values,
+     * in no particular order, into a single Flowable sequence, optionally delaying all errors.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>If {@code maxConcurrency == Integer.MAX_VALUE} the operator consumes the upstream in an unbounded manner.
@@ -8992,8 +8993,8 @@ public final <R> Flowable<R> flatMapMaybe(Function<? super T, ? extends MaybeSou
     }
 
     /**
-     * Maps each element of the upstream Flowable into SingleSources, subscribes to them and
-     * waits until the upstream and all SingleSources complete.
+     * Maps each element of the upstream Flowable into SingleSources, subscribes to all of them
+     * and merges their onSuccess values, in no particular order, into a single Flowable sequence.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator consumes the upstream in an unbounded manner.</dd>
@@ -9012,8 +9013,9 @@ public final <R> Flowable<R> flatMapSingle(Function<? super T, ? extends SingleS
     }
 
     /**
-     * Maps each element of the upstream Flowable into SingleSources, subscribes to them and
-     * waits until the upstream and all SingleSources complete, optionally delaying all errors.
+     * Maps each element of the upstream Flowable into SingleSources, subscribes to at most
+     * {@code maxConcurrency} SingleSources at a time and merges their onSuccess values,
+     * in no particular order, into a single Flowable sequence, optionally delaying all errors.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>If {@code maxConcurrency == Integer.MAX_VALUE} the operator consumes the upstream in an unbounded manner.

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

@@ -7944,8 +7944,8 @@ public final <U, V> Observable<V> flatMapIterable(final Function<? super T, ? ex
     }
 
     /**
-     * Maps each element of the upstream Observable into MaybeSources, subscribes to them and
-     * waits until the upstream and all MaybeSources complete.
+     * Maps each element of the upstream Observable into MaybeSources, subscribes to all of them
+     * and merges their onSuccess values, in no particular order, into a single Observable sequence.
      * <p>
      * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapMaybe.png" alt="">
      * <dl>
@@ -7963,8 +7963,9 @@ public final <R> Observable<R> flatMapMaybe(Function<? super T, ? extends MaybeS
     }
 
     /**
-     * Maps each element of the upstream Observable into MaybeSources, subscribes to them and
-     * waits until the upstream and all MaybeSources complete, optionally delaying all errors.
+     * Maps each element of the upstream Observable into MaybeSources, subscribes to them
+     * and merges their onSuccess values, in no particular order, into a single Observable sequence,
+     * optionally delaying all errors.
      * <p>
      * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapMaybe.png" alt="">
      * <dl>
@@ -7985,8 +7986,8 @@ public final <R> Observable<R> flatMapMaybe(Function<? super T, ? extends MaybeS
     }
 
     /**
-     * Maps each element of the upstream Observable into SingleSources, subscribes to them and
-     * waits until the upstream and all SingleSources complete.
+     * Maps each element of the upstream Observable into SingleSources, subscribes to all of them
+     * and merges their onSuccess values, in no particular order, into a single Observable sequence.
      * <p>
      * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapSingle.png" alt="">
      * <dl>
@@ -8004,8 +8005,9 @@ public final <R> Observable<R> flatMapSingle(Function<? super T, ? extends Singl
     }
 
     /**
-     * Maps each element of the upstream Observable into SingleSources, subscribes to them and
-     * waits until the upstream and all SingleSources complete, optionally delaying all errors.
+     * Maps each element of the upstream Observable into SingleSources, subscribes to them
+     * and merges their onSuccess values, in no particular order, into a single Observable sequence,
+     * optionally delaying all errors.
      * <p>
      * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapSingle.png" alt="">
      * <dl>