Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

2.x: javadoc: fix wording of some operators, remove @throws implications #4839

Merged
merged 2 commits into from
Nov 11, 2016
Merged

2.x: javadoc: fix wording of some operators, remove @throws implications #4839

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8291068
2.x: javadoc: fix wording of some operators, remove @throws implications
akarnokd Nov 11, 2016
2fbb942
Fix some introduced mistakes
akarnokd Nov 11, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 38 additions & 46 deletions src/main/java/io/reactivex/Flowable.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7718,8 +7718,8 @@ public final Flowable<T> 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.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAt.png" alt="">
* <dl>
Expand All @@ -7746,7 +7746,7 @@ public final Maybe<T> 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Revert this one?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually or use "this Flowable" like the others

* source Publisher, or a default item if that index is out of range.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAtOrDefault.png" alt="">
Expand Down Expand Up @@ -7779,9 +7779,8 @@ public final Single<T> 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.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAtOrDefault.png" alt="">
* <dl>
Expand Down Expand Up @@ -7836,8 +7835,8 @@ public final Flowable<T> filter(Predicate<? super T> 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.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/first.png" alt="">
* <dl>
Expand All @@ -7848,8 +7847,7 @@ public final Flowable<T> filter(Predicate<? super T> predicate) {
* <dd>{@code firstElement} does not operate by default on a particular {@link Scheduler}.</dd>
* </dl>
*
* @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 <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
*/
@BackpressureSupport(BackpressureKind.SPECIAL) // take may trigger UNBOUNDED_IN
Expand All @@ -7859,8 +7857,8 @@ public final Maybe<T> 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.
* <p>
* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstOrDefault.png" alt="">
* <dl>
Expand All @@ -7884,9 +7882,8 @@ public final Single<T> 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.
* <p>
* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstOrError.png" alt="">
* <dl>
Expand Down Expand Up @@ -8655,8 +8652,6 @@ public final <R> Flowable<R> flatMapSingle(Function<? super T, ? extends SingleS
* a Disposable that allows cancelling an asynchronous sequence
* @throws NullPointerException
* if {@code onNext} is null
* @throws RuntimeException
* if the Publisher calls {@code onError}
* @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
*/
@BackpressureSupport(BackpressureKind.NONE)
Expand All @@ -8682,8 +8677,6 @@ public final Disposable forEach(Consumer<? super T> 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 <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
*/
@BackpressureSupport(BackpressureKind.NONE)
Expand Down Expand Up @@ -9144,7 +9137,8 @@ public final <TRight, TLeftEnd, TRightEnd, R> Flowable<R> 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.
* <p>
* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/last.png" alt="">
* <dl>
Expand All @@ -9165,8 +9159,8 @@ public final Maybe<T> 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.
* <p>
* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrDefault.png" alt="">
* <dl>
Expand All @@ -9179,8 +9173,7 @@ public final Maybe<T> 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 <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
*/
@BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
Expand All @@ -9191,8 +9184,8 @@ public final Single<T> 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.
* <p>
* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrError.png" alt="">
* <dl>
Expand Down Expand Up @@ -11470,9 +11463,9 @@ public final Flowable<T> 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.
* <p>
* <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/single.png" alt="">
* <dl>
Expand All @@ -11484,8 +11477,6 @@ public final Flowable<T> share() {
* </dl>
*
* @return a Maybe that emits the single item emitted by the source Publisher
* @throws IllegalArgumentException
* if the source emits more than one item
* @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
*/
@BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
Expand All @@ -11497,7 +11488,7 @@ public final Maybe<T> 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.
* <p>
* <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrDefault.png" alt="">
* <dl>
Expand All @@ -11522,10 +11513,10 @@ public final Single<T> 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.
* <p>
* <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrError.png" alt="">
* <dl>
Expand Down Expand Up @@ -11894,6 +11885,9 @@ public final Flowable<T> skipWhile(Predicate<? super T> predicate) {
* sorted order. Each item emitted by the Publisher must implement {@link Comparable} with respect to all
* other items in the sequence.
*
* <p>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}.
* <p>Note that calling {@code sorted} with long, non-terminating or infinite sources
* might cause {@link OutOfMemoryError}
*
Expand All @@ -11905,9 +11899,6 @@ public final Flowable<T> skipWhile(Predicate<? super T> predicate) {
* <dd>{@code sorted} does not operate by default on a particular {@link Scheduler}.</dd>
* </dl>
*
* @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)
Expand Down Expand Up @@ -14079,6 +14070,10 @@ public final Observable<T> 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.
*
* <p>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}.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.png" alt="">
* <dl>
Expand All @@ -14088,10 +14083,6 @@ public final Observable<T> toObservable() {
* <dt><b>Scheduler:</b></dt>
* <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
* </dl>
*
* @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 <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
Expand Down Expand Up @@ -14163,6 +14154,10 @@ public final Single<List<T>> toSortedList(final Comparator<? super T> 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.
*
* <p>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}.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.png" alt="">
* <dl>
Expand All @@ -14177,9 +14172,6 @@ public final Single<List<T>> toSortedList(final Comparator<? super T> 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 <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
* @since 2.0
*/
Expand Down
Loading