Skip to content

Commit 535ab35

Browse files
akarnokdakarnokd
authored
2.x: Improve class Javadoc of Single, Maybe and Completable (#6080)
1 parent d4c1da0 commit 535ab35

File tree

3 files changed

+192
-14
lines changed

3 files changed

+192
-14
lines changed

‎src/main/java/io/reactivex/Completable.java

Lines changed: 67 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,74 @@
3333
import io.reactivex.schedulers.Schedulers;
3434

3535
/**
36-
* Represents a deferred computation without any value but only indication for completion or exception.
36+
* The {@code Completable} class represents a deferred computation without any value but
37+
* only indication for completion or exception.
38+
* <p>
39+
* {@code Completable} behaves similarly to {@link Observable} except that it can only emit either
40+
* a completion or error signal (there is no {@code onNext} or {@code onSuccess} as with the other
41+
* reactive types).
42+
* <p>
43+
* The {@code Completable} class implements the {@link CompletableSource} base interface and the default consumer
44+
* type it interacts with is the {@link CompletableObserver} via the {@link #subscribe(CompletableObserver)} method.
45+
* The {@code Completable} operates with the following sequential protocol:
46+
* <pre><code>
47+
* onSubscribe (onError | onComplete)?
48+
* </code></pre>
49+
* <p>
50+
* Note that as with the {@code Observable} protocol, {@code onError} and {@code onComplete} are mutually exclusive events.
51+
* <p>
52+
* Like {@link Observable}, a running {@code Completable} can be stopped through the {@link Disposable} instance
53+
* provided to consumers through {@link SingleObserver#onSubscribe}.
54+
* <p>
55+
* Like an {@code Observable}, a {@code Completable} is lazy, can be either "hot" or "cold", synchronous or
56+
* asynchronous. {@code Completable} instances returned by the methods of this class are <em>cold</em>
57+
* and there is a standard <em>hot</em> implementation in the form of a subject:
58+
* {@link io.reactivex.subjects.CompletableSubject CompletableSubject}.
59+
* <p>
60+
* The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
61+
* <p>
62+
* <img width="640" height="577" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.png" alt="">
63+
* <p>
64+
* See {@link Flowable} or {@link Observable} for the
65+
* implementation of the Reactive Pattern for a stream or vector of values.
66+
* <p>
67+
* Example:
68+
* <pre><code>
69+
* Disposable d = Completable.complete()
70+
* .delay(10, TimeUnit.SECONDS, Schedulers.io())
71+
* .subscribeWith(new DisposableCompletableObserver() {
72+
* &#64;Override
73+
* public void onStart() {
74+
* System.out.println("Started");
75+
* }
3776
*
38-
* The class follows a similar event pattern as Reactive-Streams: onSubscribe (onError|onComplete)?
77+
* &#64;Override
78+
* public void onError(Throwable error) {
79+
* error.printStackTrace();
80+
* }
81+
*
82+
* &#64;Override
83+
* public void onComplete() {
84+
* System.out.println("Done!");
85+
* }
86+
* });
87+
*
88+
* Thread.sleep(5000);
89+
*
90+
* d.dispose();
91+
* </code></pre>
92+
* <p>
93+
* Note that by design, subscriptions via {@link #subscribe(CompletableObserver)} can't be cancelled/disposed
94+
* from the outside (hence the
95+
* {@code void} return of the {@link #subscribe(CompletableObserver)} method) and it is the
96+
* responsibility of the implementor of the {@code CompletableObserver} to allow this to happen.
97+
* RxJava supports such usage with the standard
98+
* {@link io.reactivex.observers.DisposableCompletableObserver DisposableCompletableObserver} instance.
99+
* For convenience, the {@link #subscribeWith(CompletableObserver)} method is provided as well to
100+
* allow working with a {@code CompletableObserver} (or subclass) instance to be applied with in
101+
* a fluent manner (such as in the example above).
102+
*
103+
* @see io.reactivex.observers.DisposableCompletableObserver
39104
*/
40105
public abstract class Completable implements CompletableSource {
41106
/**

‎src/main/java/io/reactivex/Maybe.java

Lines changed: 65 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,18 +34,78 @@
3434
import io.reactivex.schedulers.Schedulers;
3535

3636
/**
37-
* Represents a deferred computation and emission of a maybe value or exception.
37+
* The {@code Maybe} class represents a deferred computation and emission of a single value, no value at all or an exception.
3838
* <p>
39-
* <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/maybe.png" alt="">
39+
* The {@code Maybe} class implements the {@link MaybeSource} base interface and the default consumer
40+
* type it interacts with is the {@link MaybeObserver} via the {@link #subscribe(MaybeObserver)} method.
4041
* <p>
41-
* The main consumer type of Maybe is {@link MaybeObserver} whose methods are called
42-
* in a sequential fashion following this protocol:<br>
43-
* {@code onSubscribe (onSuccess | onError | onComplete)?}.
42+
* The {@code Maybe} operates with the following sequential protocol:
43+
* <pre><code>
44+
* onSubscribe (onSuccess | onError | onComplete)?
45+
* </code></pre>
4446
* <p>
4547
* Note that {@code onSuccess}, {@code onError} and {@code onComplete} are mutually exclusive events; unlike {@code Observable},
4648
* {@code onSuccess} is never followed by {@code onError} or {@code onComplete}.
49+
* <p>
50+
* Like {@link Observable}, a running {@code Maybe} can be stopped through the {@link Disposable} instance
51+
* provided to consumers through {@link MaybeObserver#onSubscribe}.
52+
* <p>
53+
* Like an {@code Observable}, a {@code Maybe} is lazy, can be either "hot" or "cold", synchronous or
54+
* asynchronous. {@code Maybe} instances returned by the methods of this class are <em>cold</em>
55+
* and there is a standard <em>hot</em> implementation in the form of a subject:
56+
* {@link io.reactivex.subjects.MaybeSubject MaybeSubject}.
57+
* <p>
58+
* The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
59+
* <p>
60+
* <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/maybe.png" alt="">
61+
* <p>
62+
* See {@link Flowable} or {@link Observable} for the
63+
* implementation of the Reactive Pattern for a stream or vector of values.
64+
* <p>
65+
* Example:
66+
* <pre><code>
67+
* Disposable d = Maybe.just("Hello World")
68+
* .delay(10, TimeUnit.SECONDS, Schedulers.io())
69+
* .subscribeWith(new DisposableMaybeObserver&lt;String&gt;() {
70+
* &#64;Override
71+
* public void onStart() {
72+
* System.out.println("Started");
73+
* }
74+
*
75+
* &#64;Override
76+
* public void onSuccess(String value) {
77+
* System.out.println("Success: " + value);
78+
* }
79+
*
80+
* &#64;Override
81+
* public void onError(Throwable error) {
82+
* error.printStackTrace();
83+
* }
84+
*
85+
* &#64;Override
86+
* public void onComplete() {
87+
* System.out.println("Done!");
88+
* }
89+
* });
90+
*
91+
* Thread.sleep(5000);
92+
*
93+
* d.dispose();
94+
* </code></pre>
95+
* <p>
96+
* Note that by design, subscriptions via {@link #subscribe(MaybeObserver)} can't be cancelled/disposed
97+
* from the outside (hence the
98+
* {@code void} return of the {@link #subscribe(MaybeObserver)} method) and it is the
99+
* responsibility of the implementor of the {@code MaybeObserver} to allow this to happen.
100+
* RxJava supports such usage with the standard
101+
* {@link io.reactivex.observers.DisposableMaybeObserver DisposableMaybeObserver} instance.
102+
* For convenience, the {@link #subscribeWith(MaybeObserver)} method is provided as well to
103+
* allow working with a {@code MaybeObserver} (or subclass) instance to be applied with in
104+
* a fluent manner (such as in the example above).
105+
*
47106
* @param <T> the value type
48107
* @since 2.0
108+
* @see io.reactivex.observers.DisposableMaybeObserver
49109
*/
50110
public abstract class Maybe<T> implements MaybeSource<T> {
51111

‎src/main/java/io/reactivex/Single.java

Lines changed: 60 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,26 +37,79 @@
3737
import io.reactivex.schedulers.Schedulers;
3838

3939
/**
40-
* The Single class implements the Reactive Pattern for a single value response.
41-
* See {@link Flowable} or {@link Observable} for the
42-
* implementation of the Reactive Pattern for a stream or vector of values.
40+
* The {@code Single} class implements the Reactive Pattern for a single value response.
41+
* <p>
42+
* {@code Single} behaves similarly to {@link Observable} except that it can only emit either a single successful
43+
* value or an error (there is no "onComplete" notification as there is for an {@link Observable}).
44+
* <p>
45+
* The {@code Single} class implements the {@link SingleSource} base interface and the default consumer
46+
* type it interacts with is the {@link SingleObserver} via the {@link #subscribe(SingleObserver)} method.
47+
* <p>
48+
* The {@code Single} operates with the following sequential protocol:
49+
* <pre>
50+
* <code>onSubscribe (onSuccess | onError)?</code>
51+
* </pre>
52+
* <p>
53+
* Note that {@code onSuccess} and {@code onError} are mutually exclusive events; unlike {@code Observable},
54+
* {@code onSuccess} is never followed by {@code onError}.
4355
* <p>
44-
* {@code Single} behaves the same as {@link Observable} except that it can only emit either a single successful
45-
* value, or an error (there is no "onComplete" notification as there is for {@link Observable})
56+
* Like {@code Observable}, a running {@code Single} can be stopped through the {@link Disposable} instance
57+
* provided to consumers through {@link SingleObserver#onSubscribe}.
4658
* <p>
47-
* Like an {@link Observable}, a {@code Single} is lazy, can be either "hot" or "cold", synchronous or
48-
* asynchronous.
59+
* Like an {@code Observable}, a {@code Single} is lazy, can be either "hot" or "cold", synchronous or
60+
* asynchronous. {@code Single} instances returned by the methods of this class are <em>cold</em>
61+
* and there is a standard <em>hot</em> implementation in the form of a subject:
62+
* {@link io.reactivex.subjects.SingleSubject SingleSubject}.
4963
* <p>
5064
* The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
5165
* <p>
5266
* <img width="640" height="301" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.legend.png" alt="">
5367
* <p>
68+
* See {@link Flowable} or {@link Observable} for the
69+
* implementation of the Reactive Pattern for a stream or vector of values.
70+
* <p>
5471
* For more information see the <a href="http://reactivex.io/documentation/single.html">ReactiveX
5572
* documentation</a>.
73+
* <p>
74+
* Example:
75+
* <pre><code>
76+
* Disposable d = Single.just("Hello World")
77+
* .delay(10, TimeUnit.SECONDS, Schedulers.io())
78+
* .subscribeWith(new DisposableSingleObserver&lt;String&gt;() {
79+
* &#64;Override
80+
* public void onStart() {
81+
* System.out.println("Started");
82+
* }
83+
*
84+
* &#64;Override
85+
* public void onSuccess(String value) {
86+
* System.out.println("Success: " + value);
87+
* }
5688
*
89+
* &#64;Override
90+
* public void onError(Throwable error) {
91+
* error.printStackTrace();
92+
* }
93+
* });
94+
*
95+
* Thread.sleep(5000);
96+
*
97+
* d.dispose();
98+
* </code></pre>
99+
* <p>
100+
* Note that by design, subscriptions via {@link #subscribe(SingleObserver)} can't be cancelled/disposed
101+
* from the outside (hence the
102+
* {@code void} return of the {@link #subscribe(SingleObserver)} method) and it is the
103+
* responsibility of the implementor of the {@code SingleObserver} to allow this to happen.
104+
* RxJava supports such usage with the standard
105+
* {@link io.reactivex.observers.DisposableSingleObserver DisposableSingleObserver} instance.
106+
* For convenience, the {@link #subscribeWith(SingleObserver)} method is provided as well to
107+
* allow working with a {@code SingleObserver} (or subclass) instance to be applied with in
108+
* a fluent manner (such as in the example above).
57109
* @param <T>
58110
* the type of the item emitted by the Single
59111
* @since 2.0
112+
* @see io.reactivex.observers.DisposableSingleObserver
60113
*/
61114
public abstract class Single<T> implements SingleSource<T> {
62115

0 commit comments

Comments
 (0)