Skip to content

Commit ff66abc

Browse files
authored
2.x: javadoc: fix wording of some operators, remove @throws implications (#4839)
* 2.x: javadoc: fix wording of some operators, remove @throws implications * Fix some introduced mistakes
1 parent 36dde84 commit ff66abc

File tree

2 files changed

+76
-98
lines changed

2 files changed

+76
-98
lines changed

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

Lines changed: 39 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -7718,8 +7718,8 @@ public final Flowable<T> doOnTerminate(final Action onTerminate) {
77187718
}
77197719

77207720
/**
7721-
* Returns a Maybe that emits the single item at a specified index in a sequence of emissions from a
7722-
* source Publisher.
7721+
* Returns a Maybe that emits the single item at a specified index in a sequence of emissions from
7722+
* this Flowable or completes if this Flowable sequence has fewer elements than index.
77237723
* <p>
77247724
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAt.png" alt="">
77257725
* <dl>
@@ -7746,8 +7746,8 @@ public final Maybe<T> elementAt(long index) {
77467746
}
77477747

77487748
/**
7749-
* Returns a Flowable that emits the item found at a specified index in a sequence of emissions from a
7750-
* source Publisher, or a default item if that index is out of range.
7749+
* Returns a Flowable that emits the item found at a specified index in a sequence of emissions from
7750+
* this Flowable, or a default item if that index is out of range.
77517751
* <p>
77527752
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAtOrDefault.png" alt="">
77537753
* <dl>
@@ -7779,9 +7779,8 @@ public final Single<T> elementAt(long index, T defaultItem) {
77797779
}
77807780

77817781
/**
7782-
* Returns a Flowable that emits the item found at a specified index in a sequence of emissions from a
7783-
* source Publisher.
7784-
* If the source Publisher does not contain the item at the specified index a {@link NoSuchElementException} will be thrown.
7782+
* Returns a Flowable that emits the item found at a specified index in a sequence of emissions from
7783+
* this Flowable or signals a {@link NoSuchElementException} if this Flowable has fewer elements than index.
77857784
* <p>
77867785
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAtOrDefault.png" alt="">
77877786
* <dl>
@@ -7836,8 +7835,8 @@ public final Flowable<T> filter(Predicate<? super T> predicate) {
78367835
}
78377836

78387837
/**
7839-
* Returns a Maybe that emits only the very first item emitted by the source Publisher, or notifies
7840-
* of an {@code NoSuchElementException} if the source Publisher is empty.
7838+
* Returns a Maybe that emits only the very first item emitted by this Flowable or
7839+
* completes if this Flowable is empty.
78417840
* <p>
78427841
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/first.png" alt="">
78437842
* <dl>
@@ -7848,8 +7847,7 @@ public final Flowable<T> filter(Predicate<? super T> predicate) {
78487847
* <dd>{@code firstElement} does not operate by default on a particular {@link Scheduler}.</dd>
78497848
* </dl>
78507849
*
7851-
* @return a Maybe that emits only the very first item emitted by the source Publisher, or raises an
7852-
* {@code NoSuchElementException} if the source Publisher is empty
7850+
* @return the new Maybe instance
78537851
* @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
78547852
*/
78557853
@BackpressureSupport(BackpressureKind.SPECIAL) // take may trigger UNBOUNDED_IN
@@ -7859,8 +7857,8 @@ public final Maybe<T> firstElement() {
78597857
}
78607858

78617859
/**
7862-
* Returns a Single that emits only the very first item emitted by the source Publisher, or a default
7863-
* item if the source Publisher completes without emitting anything.
7860+
* Returns a Single that emits only the very first item emitted by this Flowable, or a default
7861+
* item if this Flowable completes without emitting anything.
78647862
* <p>
78657863
* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstOrDefault.png" alt="">
78667864
* <dl>
@@ -7884,9 +7882,8 @@ public final Single<T> first(T defaultItem) {
78847882
}
78857883

78867884
/**
7887-
* Returns a Single that emits only the very first item emitted by the source Publisher, or a default
7888-
* item if the source Publisher completes without emitting anything.
7889-
* If the source Publisher completes without emitting any items a {@link NoSuchElementException} will be thrown.
7885+
* Returns a Single that emits only the very first item emitted by this Flowable or
7886+
* signals a {@link NoSuchElementException} if this Flowable is empty.
78907887
* <p>
78917888
* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstOrError.png" alt="">
78927889
* <dl>
@@ -8655,8 +8652,6 @@ public final <R> Flowable<R> flatMapSingle(Function<? super T, ? extends SingleS
86558652
* a Disposable that allows cancelling an asynchronous sequence
86568653
* @throws NullPointerException
86578654
* if {@code onNext} is null
8658-
* @throws RuntimeException
8659-
* if the Publisher calls {@code onError}
86608655
* @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
86618656
*/
86628657
@BackpressureSupport(BackpressureKind.NONE)
@@ -8682,8 +8677,6 @@ public final Disposable forEach(Consumer<? super T> onNext) {
86828677
* a {@link Disposable} that allows cancelling an asynchronous sequence
86838678
* @throws NullPointerException
86848679
* if {@code onNext} is null
8685-
* @throws RuntimeException
8686-
* if the Publisher calls {@code onError}
86878680
* @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
86888681
*/
86898682
@BackpressureSupport(BackpressureKind.NONE)
@@ -9144,7 +9137,8 @@ public final <TRight, TLeftEnd, TRightEnd, R> Flowable<R> join(
91449137

91459138

91469139
/**
9147-
* Returns a Maybe that emits the last item emitted by the source Publisher or completes if the source Publisher is empty.
9140+
* Returns a Maybe that emits the last item emitted by this Flowable or completes if
9141+
* this Flowable is empty.
91489142
* <p>
91499143
* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/last.png" alt="">
91509144
* <dl>
@@ -9165,8 +9159,8 @@ public final Maybe<T> lastElement() {
91659159
}
91669160

91679161
/**
9168-
* Returns a Single that emits only the last item emitted by the source Publisher, or a default item
9169-
* if the source Publisher completes without emitting any items.
9162+
* Returns a Single that emits only the last item emitted by this Flowable, or a default item
9163+
* if this Flowable completes without emitting any items.
91709164
* <p>
91719165
* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrDefault.png" alt="">
91729166
* <dl>
@@ -9179,8 +9173,7 @@ public final Maybe<T> lastElement() {
91799173
*
91809174
* @param defaultItem
91819175
* the default item to emit if the source Publisher is empty
9182-
* @return a Single that emits only the last item emitted by the source Publisher, or a default item
9183-
* if the source Publisher is empty
9176+
* @return the new Single instance
91849177
* @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
91859178
*/
91869179
@BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
@@ -9191,8 +9184,8 @@ public final Single<T> last(T defaultItem) {
91919184
}
91929185

91939186
/**
9194-
* Returns a Single that emits only the last item emitted by the source Publisher.
9195-
* If the source Publisher completes without emitting any items a {@link NoSuchElementException} will be thrown.
9187+
* Returns a Single that emits only the last item emitted by this Flowable or signals
9188+
* a {@link NoSuchElementException} if this Flowable is empty.
91969189
* <p>
91979190
* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrError.png" alt="">
91989191
* <dl>
@@ -11470,9 +11463,9 @@ public final Flowable<T> share() {
1147011463
}
1147111464

1147211465
/**
11473-
* Returns a Maybe that emits the single item emitted by the source Publisher, if that Publisher
11474-
* emits only a single item. If the source Publisher emits more than one item, notify of an
11475-
* {@code IllegalArgumentException}.
11466+
* Returns a Maybe that completes if this Flowable is empty, signals one item if this Flowable
11467+
* signals exactly one item or signals an {@code IllegalArgumentException} if this Flowable signals
11468+
* more than one item.
1147611469
* <p>
1147711470
* <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/single.png" alt="">
1147811471
* <dl>
@@ -11484,8 +11477,6 @@ public final Flowable<T> share() {
1148411477
* </dl>
1148511478
*
1148611479
* @return a Maybe that emits the single item emitted by the source Publisher
11487-
* @throws IllegalArgumentException
11488-
* if the source emits more than one item
1148911480
* @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
1149011481
*/
1149111482
@BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
@@ -11497,7 +11488,7 @@ public final Maybe<T> singleElement() {
1149711488
/**
1149811489
* Returns a Single that emits the single item emitted by the source Publisher, if that Publisher
1149911490
* emits only a single item, or a default item if the source Publisher emits no items. If the source
11500-
* Publisher emits more than one item, throw an {@code IllegalArgumentException}.
11491+
* Publisher emits more than one item, an {@code IllegalArgumentException} is signalled instead.
1150111492
* <p>
1150211493
* <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrDefault.png" alt="">
1150311494
* <dl>
@@ -11522,10 +11513,10 @@ public final Single<T> single(T defaultItem) {
1152211513
}
1152311514

1152411515
/**
11525-
* Returns a Single that emits the single item emitted by the source Publisher, if that Publisher
11526-
* emits only a single item.
11527-
* If the source Publisher completes without emitting any items a {@link NoSuchElementException} will be thrown.
11528-
* If the source Publisher emits more than one item, throw an {@code IllegalArgumentException}.
11516+
* Returns a Single that emits the single item emitted by this Flowable, if this Flowable
11517+
* emits only a single item, otherwise
11518+
* if this Flowable completes without emitting any items a {@link NoSuchElementException} will be signalled and
11519+
* if this Flowable emits more than one item, an {@code IllegalArgumentException} will be signalled.
1152911520
* <p>
1153011521
* <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrError.png" alt="">
1153111522
* <dl>
@@ -11894,6 +11885,9 @@ public final Flowable<T> skipWhile(Predicate<? super T> predicate) {
1189411885
* sorted order. Each item emitted by the Publisher must implement {@link Comparable} with respect to all
1189511886
* other items in the sequence.
1189611887
*
11888+
* <p>If any item emitted by this Flowable does not implement {@link Comparable} with respect to
11889+
* all other items emitted by this Flowable, no items will be emitted and the
11890+
* sequence is terminated with a {@link ClassCastException}.
1189711891
* <p>Note that calling {@code sorted} with long, non-terminating or infinite sources
1189811892
* might cause {@link OutOfMemoryError}
1189911893
*
@@ -11905,9 +11899,6 @@ public final Flowable<T> skipWhile(Predicate<? super T> predicate) {
1190511899
* <dd>{@code sorted} does not operate by default on a particular {@link Scheduler}.</dd>
1190611900
* </dl>
1190711901
*
11908-
* @throws ClassCastException
11909-
* if any item emitted by the Publisher does not implement {@link Comparable} with respect to
11910-
* all other items emitted by the Publisher
1191111902
* @return a Flowable that emits the items emitted by the source Publisher in sorted order
1191211903
*/
1191311904
@BackpressureSupport(BackpressureKind.FULL)
@@ -14079,6 +14070,10 @@ public final Observable<T> toObservable() {
1407914070
* Returns a Single that emits a list that contains the items emitted by the source Publisher, in a
1408014071
* sorted order. Each item emitted by the Publisher must implement {@link Comparable} with respect to all
1408114072
* other items in the sequence.
14073+
*
14074+
* <p>If any item emitted by this Flowable does not implement {@link Comparable} with respect to
14075+
* all other items emitted by this Flowable, no items will be emitted and the
14076+
* sequence is terminated with a {@link ClassCastException}.
1408214077
* <p>
1408314078
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.png" alt="">
1408414079
* <dl>
@@ -14088,10 +14083,6 @@ public final Observable<T> toObservable() {
1408814083
* <dt><b>Scheduler:</b></dt>
1408914084
* <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
1409014085
* </dl>
14091-
*
14092-
* @throws ClassCastException
14093-
* if any item emitted by the Publisher does not implement {@link Comparable} with respect to
14094-
* all other items emitted by the Publisher
1409514086
* @return a Single that emits a list that contains the items emitted by the source Publisher in
1409614087
* sorted order
1409714088
* @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
@@ -14163,6 +14154,10 @@ public final Single<List<T>> toSortedList(final Comparator<? super T> comparator
1416314154
* Returns a Flowable that emits a list that contains the items emitted by the source Publisher, in a
1416414155
* sorted order. Each item emitted by the Publisher must implement {@link Comparable} with respect to all
1416514156
* other items in the sequence.
14157+
*
14158+
* <p>If any item emitted by this Flowable does not implement {@link Comparable} with respect to
14159+
* all other items emitted by this Flowable, no items will be emitted and the
14160+
* sequence is terminated with a {@link ClassCastException}.
1416614161
* <p>
1416714162
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.png" alt="">
1416814163
* <dl>
@@ -14177,9 +14172,6 @@ public final Single<List<T>> toSortedList(final Comparator<? super T> comparator
1417714172
* the initial capacity of the ArrayList used to accumulate items before sorting
1417814173
* @return a Flowable that emits a list that contains the items emitted by the source Publisher in
1417914174
* sorted order
14180-
* @throws ClassCastException
14181-
* if any item emitted by the Publisher does not implement {@link Comparable} with respect to
14182-
* all other items emitted by the Publisher
1418314175
* @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
1418414176
* @since 2.0
1418514177
*/

0 commit comments

Comments
 (0)