2.x: Describe merge() error handling.

[akarnokd]

This PR adds some clarifications about how merge handles (multiple) errors in a new Error handling section in its <dl> JavaDoc entry.

There exist several dozen variants of merge in the various base classes that could also include such JavaDoc addition. Once the wording has been reviewed, the other places will receive a separate PR.

Related: #5779, #5780

[codecov]

Codecov Report

Merging #5781 into 2.x will decrease coverage by 0.01%.
The diff coverage is n/a.

@@             Coverage Diff              @@
##                2.x    #5781      +/-   ##
============================================
- Coverage     96.27%   96.26%   -0.02%     
- Complexity     5807     5810       +3     
============================================
  Files           634      634              
  Lines         41607    41607              
  Branches       5770     5770              
============================================
- Hits          40057    40052       -5     
- Misses          611      620       +9     
+ Partials        939      935       -4

Impacted Files	Coverage Δ	Complexity Δ
src/main/java/io/reactivex/Flowable.java	100% <ø> (ø)	526 <0> (ø)	⬇️
.../operators/observable/ObservableFlatMapSingle.java	88.8% <0%> (-6.72%)	2% <0%> (ø)
...in/java/io/reactivex/subjects/BehaviorSubject.java	86.24% <0%> (-5.83%)	54% <0%> (ø)
...erators/completable/CompletableConcatIterable.java	95.91% <0%> (-4.09%)	2% <0%> (ø)
...l/operators/observable/ObservableFlatMapMaybe.java	84.96% <0%> (-3.93%)	2% <0%> (ø)
...vex/internal/operators/single/SingleTakeUntil.java	91.8% <0%> (-3.28%)	2% <0%> (ø)
...a/io/reactivex/internal/util/QueueDrainHelper.java	61.8% <0%> (-2.78%)	35% <0%> (-2%)
...ain/java/io/reactivex/subjects/PublishSubject.java	97.8% <0%> (-2.2%)	38% <0%> (-1%)
...rnal/operators/flowable/FlowableFlatMapSingle.java	92.93% <0%> (-2.18%)	2% <0%> (ø)
.../internal/disposables/ListCompositeDisposable.java	98% <0%> (-2%)	34% <0%> (-1%)
... and 30 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7e503f0...c584452. Read the comment docs.

[vanniktech]

Does Observable already have this section?

[akarnokd]

No. This acts as a testbed for the wording. I hope @artem-zinnatulin can have a look at it too before I copy the text all over the place.

[tony-root]

Does it make sense to explicitly state that split-merge pattern like

PublishSubject<Boolean> ps = PublishSubject.create();

Observable.merge(
        ps.filter((condition) -> condition),
        ps.filter((condition) -> !condition)
).subscribe(
        (next) -> { },
        (error) -> error.printStackTrace()
);

ps.onError(new RuntimeException("Will cause UndeliverableException"));

is guaranteed to produce an UndeliverableException in addition to onError?

Maybe in Wiki instead of javadoc?

[akarnokd]

The main effect is the merge here, not the split. Also I'm not sure how often people find out about this behavior through this split-merge pattern.

[tony-root]

Indeed merge is the main reason, however every time people use split-merge and don't find out about this behavior they introduce a potential hard-to-find bug.

It still seems to me that merge should by default behave like mergeFirstErrorOnly from #5779 discussion, but I'm definitely not pushing.