From 82910680c7bae1033ce004ea7abe55170c62a366 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1vid=20Karnok?= Date: Fri, 11 Nov 2016 23:33:18 +0100 Subject: [PATCH 1/2] 2.x: javadoc: fix wording of some operators, remove @throws implications --- src/main/java/io/reactivex/Flowable.java | 84 ++++++++++----------- src/main/java/io/reactivex/Observable.java | 86 +++++++++------------- 2 files changed, 74 insertions(+), 96 deletions(-) diff --git a/src/main/java/io/reactivex/Flowable.java b/src/main/java/io/reactivex/Flowable.java index b6234d4c1d..9aee3da73b 100644 --- a/src/main/java/io/reactivex/Flowable.java +++ b/src/main/java/io/reactivex/Flowable.java @@ -7718,8 +7718,8 @@ public final Flowable doOnTerminate(final Action onTerminate) { } /** - * Returns a Maybe that emits the single item at a specified index in a sequence of emissions from a - * source Publisher. + * Returns a Maybe that emits the single item at a specified index in a sequence of emissions from + * this Flowable or completes if this Flowable sequence has fewer elements than index. *

* *

@@ -7746,7 +7746,7 @@ public final Maybe elementAt(long index) { } /** - * Returns a Flowable that emits the item found at a specified index in a sequence of emissions from a + * Returns a Flowable that emits the item found at a specified index in a sequence of emissions from * source Publisher, or a default item if that index is out of range. *

* @@ -7779,9 +7779,8 @@ public final Single elementAt(long index, T defaultItem) { } /** - * Returns a Flowable that emits the item found at a specified index in a sequence of emissions from a - * source Publisher. - * If the source Publisher does not contain the item at the specified index a {@link NoSuchElementException} will be thrown. + * Returns a Flowable that emits the item found at a specified index in a sequence of emissions from + * this Flowable or signals a {@link NoSuchElementException} if this Flowable has fewer elements than index. *

* *

@@ -7836,8 +7835,8 @@ public final Flowable filter(Predicate predicate) { } /** - * Returns a Maybe that emits only the very first item emitted by the source Publisher, or notifies - * of an {@code NoSuchElementException} if the source Publisher is empty. + * Returns a Maybe that emits only the very first item emitted by this Flowable or + * completes if this Flowable is empty. *

* *

@@ -7848,8 +7847,7 @@ public final Flowable filter(Predicate predicate) { *
{@code firstElement} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a Maybe that emits only the very first item emitted by the source Publisher, or raises an - * {@code NoSuchElementException} if the source Publisher is empty + * @return the new Maybe instance * @see ReactiveX operators documentation: First */ @BackpressureSupport(BackpressureKind.SPECIAL) // take may trigger UNBOUNDED_IN @@ -7859,8 +7857,8 @@ public final Maybe firstElement() { } /** - * Returns a Single that emits only the very first item emitted by the source Publisher, or a default - * item if the source Publisher completes without emitting anything. + * Returns a Single that emits only the very first item emitted by this Flowable, or a default + * item if this Flowable completes without emitting anything. *

* *

@@ -7884,9 +7882,8 @@ public final Single first(T defaultItem) { } /** - * Returns a Single that emits only the very first item emitted by the source Publisher, or a default - * item if the source Publisher completes without emitting anything. - * If the source Publisher completes without emitting any items a {@link NoSuchElementException} will be thrown. + * Returns a Single that emits only the very first item emitted by this Flowable or + * signals a {@link NoSuchElementException} if this Flowable is empty. *

* *

@@ -8655,8 +8652,6 @@ public final Flowable flatMapSingle(FunctionReactiveX operators documentation: Subscribe */ @BackpressureSupport(BackpressureKind.NONE) @@ -8682,8 +8677,6 @@ public final Disposable forEach(Consumer onNext) { * a {@link Disposable} that allows cancelling an asynchronous sequence * @throws NullPointerException * if {@code onNext} is null - * @throws RuntimeException - * if the Publisher calls {@code onError} * @see ReactiveX operators documentation: Subscribe */ @BackpressureSupport(BackpressureKind.NONE) @@ -9144,7 +9137,8 @@ public final Flowable join( /** - * Returns a Maybe that emits the last item emitted by the source Publisher or completes if the source Publisher is empty. + * Returns a Maybe that emits the last item emitted by this Flowable or completes if + * this Flowable is empty. *

* *

@@ -9165,8 +9159,8 @@ public final Maybe lastElement() { } /** - * Returns a Single that emits only the last item emitted by the source Publisher, or a default item - * if the source Publisher completes without emitting any items. + * Returns a Single that emits only the last item emitted by this Flowable, or a default item + * if this Flowable completes without emitting any items. *

* *

@@ -9179,8 +9173,7 @@ public final Maybe lastElement() { * * @param defaultItem * the default item to emit if the source Publisher is empty - * @return a Single that emits only the last item emitted by the source Publisher, or a default item - * if the source Publisher is empty + * @return the new Single instance * @see ReactiveX operators documentation: Last */ @BackpressureSupport(BackpressureKind.UNBOUNDED_IN) @@ -9191,8 +9184,8 @@ public final Single last(T defaultItem) { } /** - * Returns a Single that emits only the last item emitted by the source Publisher. - * If the source Publisher completes without emitting any items a {@link NoSuchElementException} will be thrown. + * Returns a Single that emits only the last item emitted by this Flowable or signals + * a {@link NoSuchElementException} if this Flowable is empty. *

* *

@@ -11470,9 +11463,9 @@ public final Flowable share() { } /** - * Returns a Maybe that emits the single item emitted by the source Publisher, if that Publisher - * emits only a single item. If the source Publisher emits more than one item, notify of an - * {@code IllegalArgumentException}. + * Returns a Maybe that completes if this Flowable is empty, signals one item if this Flowable + * signals exactly one item or signals an {@code IllegalArgumentException} if this Flowable signals + * more than one item. *

* *

@@ -11484,8 +11477,6 @@ public final Flowable share() { *
* * @return a Maybe that emits the single item emitted by the source Publisher - * @throws IllegalArgumentException - * if the source emits more than one item * @see ReactiveX operators documentation: First */ @BackpressureSupport(BackpressureKind.UNBOUNDED_IN) @@ -11497,7 +11488,7 @@ public final Maybe singleElement() { /** * Returns a Single that emits the single item emitted by the source Publisher, if that Publisher * emits only a single item, or a default item if the source Publisher emits no items. If the source - * Publisher emits more than one item, throw an {@code IllegalArgumentException}. + * Publisher emits more than one item, an {@code IllegalArgumentException} is signalled instead. *

* *

@@ -11522,10 +11513,10 @@ public final Single single(T defaultItem) { } /** - * Returns a Single that emits the single item emitted by the source Publisher, if that Publisher - * emits only a single item. - * If the source Publisher completes without emitting any items a {@link NoSuchElementException} will be thrown. - * If the source Publisher emits more than one item, throw an {@code IllegalArgumentException}. + * Returns a Single that emits the single item emitted by this Flowable, if this Flowable + * emits only a single item, otherwise + * if this Flowable completes without emitting any items a {@link NoSuchElementException} will be signalled and + * if this Flowable emits more than one item, an {@code IllegalArgumentException} will be signalled. *

* *

@@ -11894,6 +11885,9 @@ public final Flowable skipWhile(Predicate predicate) { * sorted order. Each item emitted by the Publisher must implement {@link Comparable} with respect to all * other items in the sequence. * + *

If any item emitted by this Flowable does not implement {@link Comparable} with respect to + * all other items emitted by this Flowable, no items will be emitted and the + * sequence is terminated with a {@link ClassCastException}. *

Note that calling {@code sorted} with long, non-terminating or infinite sources * might cause {@link OutOfMemoryError} * @@ -11905,9 +11899,6 @@ public final Flowable skipWhile(Predicate predicate) { *

{@code sorted} does not operate by default on a particular {@link Scheduler}.
*
* - * @throws ClassCastException - * if any item emitted by the Publisher does not implement {@link Comparable} with respect to - * all other items emitted by the Publisher * @return a Flowable that emits the items emitted by the source Publisher in sorted order */ @BackpressureSupport(BackpressureKind.FULL) @@ -14079,6 +14070,10 @@ public final Observable toObservable() { * Returns a Single that emits a list that contains the items emitted by the source Publisher, in a * sorted order. Each item emitted by the Publisher must implement {@link Comparable} with respect to all * other items in the sequence. + * + *

If any item emitted by this Flowable does not implement {@link Comparable} with respect to + * all other items emitted by this Flowable, no items will be emitted and the + * sequence is terminated with a {@link ClassCastException}. *

* *

@@ -14088,10 +14083,6 @@ public final Observable toObservable() { *
Scheduler:
*
{@code toSortedList} does not operate by default on a particular {@link Scheduler}.
*
- * - * @throws ClassCastException - * if any item emitted by the Publisher does not implement {@link Comparable} with respect to - * all other items emitted by the Publisher * @return a Single that emits a list that contains the items emitted by the source Publisher in * sorted order * @see ReactiveX operators documentation: To @@ -14163,6 +14154,10 @@ public final Single> toSortedList(final Comparator comparator * Returns a Flowable that emits a list that contains the items emitted by the source Publisher, in a * sorted order. Each item emitted by the Publisher must implement {@link Comparable} with respect to all * other items in the sequence. + * + *

If any item emitted by this Flowable does not implement {@link Comparable} with respect to + * all other items emitted by this Flowable, no items will be emitted and the + * sequence is terminated with a {@link ClassCastException}. *

* *

@@ -14177,9 +14172,6 @@ public final Single> toSortedList(final Comparator comparator * the initial capacity of the ArrayList used to accumulate items before sorting * @return a Flowable that emits a list that contains the items emitted by the source Publisher in * sorted order - * @throws ClassCastException - * if any item emitted by the Publisher does not implement {@link Comparable} with respect to - * all other items emitted by the Publisher * @see ReactiveX operators documentation: To * @since 2.0 */ diff --git a/src/main/java/io/reactivex/Observable.java b/src/main/java/io/reactivex/Observable.java index 974b9498c1..b8338d56a8 100644 --- a/src/main/java/io/reactivex/Observable.java +++ b/src/main/java/io/reactivex/Observable.java @@ -6722,8 +6722,8 @@ public final Observable doOnTerminate(final Action onTerminate) { } /** - * Returns a Maybe that emits the single item at a specified index in a sequence of emissions from a - * source ObservableSource. + * Returns a Maybe that emits the single item at a specified index in a sequence of emissions from + * this Observable or completes if this Observable signals fewer elements than index. *

* *

@@ -6748,8 +6748,8 @@ public final Maybe elementAt(long index) { } /** - * Returns a Single that emits the item found at a specified index in a sequence of emissions from a - * source ObservableSource, or a default item if that index is out of range. + * Returns a Single that emits the item found at a specified index in a sequence of emissions from + * this Observable, or a default item if that index is out of range. *

* *

@@ -6777,8 +6777,8 @@ public final Single elementAt(long index, T defaultItem) { } /** - * Returns a Single that emits the item found at a specified index in a sequence of emissions from a source ObservableSource. - * If the source ObservableSource does not contain the item at the specified index a {@link NoSuchElementException} will be thrown. + * Returns a Single that emits the item found at a specified index in a sequence of emissions from this Observable + * or signals a {@link NoSuchElementException} if this Observable signals fewer elements than index. *

* *

@@ -6863,8 +6863,8 @@ public final Single first(T defaultItem) { } /** - * Returns a Single that emits only the very first item emitted by the source ObservableSource. - * If the source ObservableSource completes without emitting any items a {@link NoSuchElementException} will be thrown. + * Returns a Single that emits only the very first item emitted by this Observable or + * signals a {@link NoSuchElementException} if this Observable is empty. *

* *

@@ -7466,8 +7466,6 @@ public final Observable flatMapSingle(FunctionReactiveX operators documentation: Subscribe */ @SchedulerSupport(SchedulerSupport.NONE) @@ -7489,8 +7487,6 @@ public final Disposable forEach(Consumer onNext) { * a Disposable that allows cancelling an asynchronous sequence * @throws NullPointerException * if {@code onNext} is null - * @throws RuntimeException - * if the ObservableSource calls {@code onError} * @see ReactiveX operators documentation: Subscribe */ @SchedulerSupport(SchedulerSupport.NONE) @@ -7889,8 +7885,8 @@ public final Observable join( } /** - * Returns a Maybe that emits the last item emitted by the source ObservableSource or - * completes if the source is empty. + * Returns a Maybe that emits the last item emitted by this Observable or + * completes if this Observable is empty. *

* *

@@ -7908,8 +7904,8 @@ public final Maybe lastElement() { } /** - * Returns a Single that emits only the last item emitted by the source ObservableSource, or a default item - * if the source ObservableSource completes without emitting any items. + * Returns a Single that emits only the last item emitted by this Observable, or a default item + * if this Observable completes without emitting any items. *

* *

@@ -7930,8 +7926,8 @@ public final Single last(T defaultItem) { } /** - * Returns a Single that emits only the last item emitted by the source ObservableSource. - * If the source ObservableSource completes without emitting any items a {@link NoSuchElementException} will be thrown. + * Returns a Single that emits only the last item emitted by this Observable or + * signals a {@link NoSuchElementException} if this Observable is empty. *

* *

@@ -8415,8 +8411,6 @@ public final Observable publish(Function, ? extends * result will be used in the next accumulator call * @return a Maybe that emits a single item that is the result of accumulating the items emitted by * the source ObservableSource - * @throws IllegalArgumentException - * if the source ObservableSource emits no items * @see ReactiveX operators documentation: Reduce * @see Wikipedia: Fold (higher-order function) */ @@ -9537,9 +9531,9 @@ public final Observable share() { } /** - * Returns an Observable that emits the single item emitted by the source ObservableSource, if that ObservableSource - * emits only a single item. If the source ObservableSource emits more than one item or no items, notify of an - * {@code IllegalArgumentException} or {@code NoSuchElementException} respectively. + * Returns an Observable that emits the single item emitted by this Observable if this Observable + * emits only a single item, otherwise if this Observable emits more than one item or no items, an + * {@code IllegalArgumentException} or {@code NoSuchElementException} is signalled respectively. *

* *

@@ -9548,10 +9542,6 @@ public final Observable share() { *
* * @return an Observable that emits the single item emitted by the source ObservableSource - * @throws IllegalArgumentException - * if the source emits more than one item - * @throws NoSuchElementException - * if the source emits no items * @see ReactiveX operators documentation: First */ @SchedulerSupport(SchedulerSupport.NONE) @@ -9560,9 +9550,9 @@ public final Maybe singleElement() { } /** - * Returns a Single that emits the single item emitted by the source ObservableSource, if that ObservableSource + * Returns a Single that emits the single item emitted by this Observable, if this Observable * emits only a single item, or a default item if the source ObservableSource emits no items. If the source - * ObservableSource emits more than one item, throw an {@code IllegalArgumentException}. + * ObservableSource emits more than one item, an {@code IllegalArgumentException} is signalled instead. *

* *

@@ -9573,8 +9563,6 @@ public final Maybe singleElement() { * @param defaultItem * a default value to emit if the source ObservableSource emits no item * @return the new Single instance - * @throws IllegalArgumentException - * if the source ObservableSource emits more than one item * @see ReactiveX operators documentation: First */ @SchedulerSupport(SchedulerSupport.NONE) @@ -9584,10 +9572,10 @@ public final Single single(T defaultItem) { } /** - * Returns a Single that emits the single item emitted by the source ObservableSource, if that ObservableSource - * emits only a single item. - * If the source ObservableSource completes without emitting any items a {@link NoSuchElementException} will be thrown. - * If the source ObservableSource emits more than one item, throw an {@code IllegalArgumentException}. + * Returns a Single that emits the single item emitted by this Observalbe if this Observable + * emits only a single item, otherwise + * if this Observable completes without emitting any items or emits more than one item a + * {@link NoSuchElementException} or {@code IllegalArgumentException} will be signalled respectively. *

* *

@@ -9596,10 +9584,6 @@ public final Single single(T defaultItem) { *
* * @return the new Single instance - * @throws IllegalArgumentException - * if the source ObservableSource emits more than one item - * @throws NoSuchElementException - * if the source ObservableSource completes without emitting any items * @see ReactiveX operators documentation: First */ @SchedulerSupport(SchedulerSupport.NONE) @@ -9913,6 +9897,10 @@ public final Observable skipWhile(Predicate predicate) { * sorted order. Each item emitted by the ObservableSource must implement {@link Comparable} with respect to all * other items in the sequence. * + *

If any item emitted by this Observable does not implement {@link Comparable} with respect to + * all other items emitted by this Observable, no items will be emitted and the + * sequence is terminated with a {@link ClassCastException}. + * *

Note that calling {@code sorted} with long, non-terminating or infinite sources * might cause {@link OutOfMemoryError} * @@ -9920,10 +9908,6 @@ public final Observable skipWhile(Predicate predicate) { *

Scheduler:
*
{@code sorted} does not operate by default on a particular {@link Scheduler}.
*
- * - * @throws ClassCastException - * if any item emitted by the ObservableSource does not implement {@link Comparable} with respect to - * all other items emitted by the ObservableSource * @return an Observable that emits the items emitted by the source ObservableSource in sorted order */ @SchedulerSupport(SchedulerSupport.NONE) @@ -11344,6 +11328,7 @@ public final Observable timeout(ObservableSource firstTimeoutIndica * within time windows defined by the timeout selectors * @throws NullPointerException * if {@code itemTimeoutIndicator} is null + * if {@code other} is null * @see ReactiveX operators documentation: Timeout */ @SchedulerSupport(SchedulerSupport.NONE) @@ -11815,16 +11800,16 @@ public final Flowable toFlowable(BackpressureStrategy strategy) { * Returns a Single that emits a list that contains the items emitted by the source ObservableSource, in a * sorted order. Each item emitted by the ObservableSource must implement {@link Comparable} with respect to all * other items in the sequence. + * + *

If any item emitted by this Observable does not implement {@link Comparable} with respect to + * all other items emitted by this Observable, no items will be emitted and the + * sequence is terminated with a {@link ClassCastException}. *

* *

*
Scheduler:
*
{@code toSortedList} does not operate by default on a particular {@link Scheduler}.
*
- * - * @throws ClassCastException - * if any item emitted by the ObservableSource does not implement {@link Comparable} with respect to - * all other items emitted by the ObservableSource * @return a Single that emits a list that contains the items emitted by the source ObservableSource in * sorted order * @see ReactiveX operators documentation: To @@ -11887,6 +11872,10 @@ public final Single> toSortedList(final Comparator comparator * Returns a Single that emits a list that contains the items emitted by the source ObservableSource, in a * sorted order. Each item emitted by the ObservableSource must implement {@link Comparable} with respect to all * other items in the sequence. + * + *

If any item emitted by this Observable does not implement {@link Comparable} with respect to + * all other items emitted by this Observable, no items will be emitted and the + * sequence is terminated with a {@link ClassCastException}. *

* *

@@ -11898,9 +11887,6 @@ public final Single> toSortedList(final Comparator comparator * the initial capacity of the ArrayList used to accumulate items before sorting * @return a Single that emits a list that contains the items emitted by the source ObservableSource in * sorted order - * @throws ClassCastException - * if any item emitted by the ObservableSource does not implement {@link Comparable} with respect to - * all other items emitted by the ObservableSource * @see ReactiveX operators documentation: To * @since 2.0 */ From 2fbb94234181c99cbe5b3b2b5876366f96e66eae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1vid=20Karnok?= Date: Fri, 11 Nov 2016 23:58:15 +0100 Subject: [PATCH 2/2] Fix some introduced mistakes --- src/main/java/io/reactivex/Flowable.java | 2 +- src/main/java/io/reactivex/Observable.java | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/main/java/io/reactivex/Flowable.java b/src/main/java/io/reactivex/Flowable.java index 9aee3da73b..92ad7ae1d6 100644 --- a/src/main/java/io/reactivex/Flowable.java +++ b/src/main/java/io/reactivex/Flowable.java @@ -7747,7 +7747,7 @@ public final Maybe elementAt(long index) { /** * Returns a Flowable that emits the item found at a specified index in a sequence of emissions from - * source Publisher, or a default item if that index is out of range. + * this Flowable, or a default item if that index is out of range. *

* *

diff --git a/src/main/java/io/reactivex/Observable.java b/src/main/java/io/reactivex/Observable.java index b8338d56a8..4b42c374a0 100644 --- a/src/main/java/io/reactivex/Observable.java +++ b/src/main/java/io/reactivex/Observable.java @@ -11327,7 +11327,7 @@ public final Observable timeout(ObservableSource firstTimeoutIndica * either the first item emitted by the source ObservableSource or any subsequent item doesn't arrive * within time windows defined by the timeout selectors * @throws NullPointerException - * if {@code itemTimeoutIndicator} is null + * if {@code itemTimeoutIndicator} is null, or * if {@code other} is null * @see ReactiveX operators documentation: Timeout */