From 3f9ffae961506ba560a8d43e936a94eb5f563d3c Mon Sep 17 00:00:00 2001
From: David Karnok <akarnokd@gmail.com>
Date: Thu, 9 Nov 2017 01:07:54 +0100
Subject: [PATCH] 2.x: Improve Javadocs of flatMapSingle and flatMapMaybe
 (#5709)

---
 src/main/java/io/reactivex/Flowable.java   | 18 ++++++++++--------
 src/main/java/io/reactivex/Observable.java | 18 ++++++++++--------
 2 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/src/main/java/io/reactivex/Flowable.java b/src/main/java/io/reactivex/Flowable.java
index 56908d2050..d15f735a44 100644
--- a/src/main/java/io/reactivex/Flowable.java
+++ b/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.
diff --git a/src/main/java/io/reactivex/Observable.java b/src/main/java/io/reactivex/Observable.java
index 38baae0931..ba82c99c7a 100644
--- a/src/main/java/io/reactivex/Observable.java
+++ b/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>