Skip to content

Commit dc12d5b

Browse files
daveraydaveray
committed
Various Javadoc improvements and corrections.
1 parent f651b7a commit dc12d5b

12 files changed

Lines changed: 598 additions & 531 deletions

File tree

‎rxjava-core/src/main/java/rx/Observable.java‎

Lines changed: 438 additions & 403 deletions
Large diffs are not rendered by default.

‎rxjava-core/src/main/java/rx/Observer.java‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
/**
22
* Copyright 2013 Netflix, Inc.
3-
*
3+
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
66
* You may obtain a copy of the License at
7-
*
7+
*
88
* http://www.apache.org/licenses/LICENSE-2.0
9-
*
9+
*
1010
* Unless required by applicable law or agreed to in writing, software
1111
* distributed under the License is distributed on an "AS IS" BASIS,
1212
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -18,12 +18,12 @@
1818
/**
1919
* Provides a mechanism for receiving push-based notifications.
2020
* <p>
21-
* After an Observer calls an {@link Observable}'s <code>Observable.subscribe</code> method, the {@link Observable} calls the Observer's <code>onNext</code> method to provide notifications. A
22-
* well-behaved {@link Observable} will
21+
* After an Observer calls an {@link Observable}'s <code>Observable.subscribe</code> method, the {@link Observable}
22+
* calls the Observer's <code>onNext</code> method to provide notifications. A well-behaved {@link Observable} will
2323
* call an Observer's <code>onCompleted</code> closure exactly once or the Observer's <code>onError</code> closure exactly once.
2424
* <p>
2525
* For more information see the <a href="https://github.com/Netflix/RxJava/wiki/Observable">RxJava Wiki</a>
26-
*
26+
*
2727
* @param <T>
2828
*/
2929
public interface Observer<T> {
@@ -39,7 +39,7 @@ public interface Observer<T> {
3939
* Notifies the Observer that the {@link Observable} has experienced an error condition.
4040
* <p>
4141
* If the {@link Observable} calls this closure, it will not thereafter call <code>onNext</code> or <code>onCompleted</code>.
42-
*
42+
*
4343
* @param e
4444
*/
4545
public void onError(Exception e);
@@ -50,7 +50,7 @@ public interface Observer<T> {
5050
* The {@link Observable} calls this closure 1 or more times, unless it calls <code>onError</code> in which case this closure may never be called.
5151
* <p>
5252
* The {@link Observable} will not call this closure again after it calls either <code>onCompleted</code> or <code>onError</code>.
53-
*
53+
*
5454
* @param args
5555
*/
5656
public void onNext(T args);

‎rxjava-core/src/main/java/rx/Subscription.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@
2121
* Subscription returns from {@link Observable#subscribe(Observer)} to allow unsubscribing.
2222
* <p>
2323
* See utilities in {@link Subscriptions} and implementations in the {@link rx.subscriptions} package.
24+
* <p>
25+
* This interface is the RxJava equivalent of {@code IDisposable} in Microsoft's Rx implementation.
2426
*/
2527
public interface Subscription {
2628

‎rxjava-core/src/main/java/rx/observables/GroupedObservable.java‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
/**
22
* Copyright 2013 Netflix, Inc.
3-
*
3+
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
66
* You may obtain a copy of the License at
7-
*
7+
*
88
* http://www.apache.org/licenses/LICENSE-2.0
9-
*
9+
*
1010
* Unless required by applicable law or agreed to in writing, software
1111
* distributed under the License is distributed on an "AS IS" BASIS,
1212
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -23,11 +23,11 @@
2323
/**
2424
* An {@link Observable} that has been grouped by a key whose value can be obtained using
2525
* {@link #getKey()} <p>
26-
*
26+
*
2727
* @see Observable#groupBy(Observable, Func1)
28-
*
29-
* @param <K>
30-
* @param <T>
28+
*
29+
* @param <K> the type of the key
30+
* @param <T> the type of the elements in the group
3131
*/
3232
public class GroupedObservable<K, T> extends Observable<T> {
3333
private final K key;
@@ -37,8 +37,13 @@ public GroupedObservable(K key, Func1<Observer<T>, Subscription> onSubscribe) {
3737
this.key = key;
3838
}
3939

40+
/**
41+
* Returns the key the elements in this observable were grouped by.
42+
*
43+
* @return the key the elements in this observable were grouped by
44+
*/
4045
public K getKey() {
4146
return key;
4247
}
43-
4448
}
49+

‎rxjava-core/src/main/java/rx/package-info.java‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
/**
22
* Copyright 2013 Netflix, Inc.
3-
*
3+
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
66
* You may obtain a copy of the License at
7-
*
7+
*
88
* http://www.apache.org/licenses/LICENSE-2.0
9-
*
9+
*
1010
* Unless required by applicable law or agreed to in writing, software
1111
* distributed under the License is distributed on an "AS IS" BASIS,
1212
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -15,7 +15,7 @@
1515
*/
1616
/**
1717
* <p>Rx Observables</p>
18-
*
18+
*
1919
* <p>A library that enables subscribing to and composing asynchronous events and
2020
* callbacks.</p>
2121
* <p>The Observable/Observer interfaces and associated operators (in
@@ -25,8 +25,8 @@
2525
* More information can be found at <a
2626
* href="http://msdn.microsoft.com/en-us/data/gg577609">http://msdn.microsoft.com/en-us/data/gg577609</a>.
2727
* </p>
28-
*
29-
*
28+
*
29+
*
3030
* <p>Compared with the Microsoft implementation:
3131
* <ul>
3232
* <li>Observable == IObservable</li>
@@ -37,9 +37,8 @@
3737
* </p>
3838
* <p>Services which intend on exposing data asynchronously and wish
3939
* to allow reactive processing and composition can implement the
40-
* Watchable interface which then allows Watchers to subscribe to them
40+
* {@link rx.Observable} interface which then allows Observers to subscribe to them
4141
* and receive events.</p>
42-
* <p>Usage examples can be found on the Watchable and Watcher
43-
* classes.</p>
42+
* <p>Usage examples can be found on the {@link rx.Observable} and {@link rx.Observer} classes.</p>
4443
*/
45-
package rx;
44+
package rx;

‎rxjava-core/src/main/java/rx/subjects/AsyncSubject.java‎

Lines changed: 24 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
/**
22
* Copyright 2013 Netflix, Inc.
3-
*
3+
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
66
* You may obtain a copy of the License at
7-
*
7+
*
88
* http://www.apache.org/licenses/LICENSE-2.0
9-
*
9+
*
1010
* Unless required by applicable law or agreed to in writing, software
1111
* distributed under the License is distributed on an "AS IS" BASIS,
1212
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -32,33 +32,41 @@
3232
import rx.util.functions.Func1;
3333

3434
/**
35-
* Subject that publishes only the last event to each {@link Observer} that has subscribed when the completes.
35+
* Subject that publishes only the last event to each {@link Observer} that has subscribed when the
36+
* sequence completes.
37+
*
3638
* <p>
3739
* Example usage:
3840
* <p>
3941
* <pre> {@code
40-
41-
// observer will receive no onNext events.
42+
43+
// observer will receive no onNext events because the subject.onCompleted() isn't called.
4244
AsyncSubject<Object> subject = AsyncSubject.create();
4345
subject.subscribe(observer);
4446
subject.onNext("one");
4547
subject.onNext("two");
4648
subject.onNext("three");
47-
49+
4850
// observer will receive "three" as the only onNext event.
4951
AsyncSubject<Object> subject = AsyncSubject.create();
5052
subject.subscribe(observer);
5153
subject.onNext("one");
5254
subject.onNext("two");
5355
subject.onNext("three");
5456
subject.onCompleted();
55-
57+
5658
} </pre>
57-
*
59+
*
5860
* @param <T>
5961
*/
6062
public class AsyncSubject<T> extends Subject<T, T> {
61-
63+
64+
65+
/**
66+
* Create a new AsyncSubject
67+
*
68+
* @return a new AsyncSubject
69+
*/
6270
public static <T> AsyncSubject<T> create() {
6371
final ConcurrentHashMap<Subscription, Observer<T>> observers = new ConcurrentHashMap<Subscription, Observer<T>>();
6472

@@ -95,10 +103,10 @@ protected AsyncSubject(Func1<Observer<T>, Subscription> onSubscribe, ConcurrentH
95103

96104
@Override
97105
public void onCompleted() {
98-
T finalValue = currentValue.get();
99-
for (Observer<T> observer : observers.values()) {
100-
observer.onNext(finalValue);
101-
}
106+
T finalValue = currentValue.get();
107+
for (Observer<T> observer : observers.values()) {
108+
observer.onNext(finalValue);
109+
}
102110
for (Observer<T> observer : observers.values()) {
103111
observer.onCompleted();
104112
}
@@ -141,7 +149,7 @@ private void assertNeverCompletedObserver(Observer<String> aObserver)
141149
verify(aObserver, Mockito.never()).onError(testException);
142150
verify(aObserver, Mockito.never()).onCompleted();
143151
}
144-
152+
145153
@Test
146154
public void testCompleted() {
147155
AsyncSubject<Object> subject = AsyncSubject.create();
@@ -242,7 +250,7 @@ public void call(AsyncSubject<Object> DefaultSubject)
242250
{
243251
DefaultSubject.onError(new Exception());
244252
}
245-
},
253+
},
246254
null);
247255
}
248256
}

‎rxjava-core/src/main/java/rx/subjects/BehaviorSubject.java‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
/**
22
* Copyright 2013 Netflix, Inc.
3-
*
3+
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
66
* You may obtain a copy of the License at
7-
*
7+
*
88
* http://www.apache.org/licenses/LICENSE-2.0
9-
*
9+
*
1010
* Unless required by applicable law or agreed to in writing, software
1111
* distributed under the License is distributed on an "AS IS" BASIS,
1212
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -32,46 +32,48 @@
3232
import rx.util.functions.Func1;
3333

3434
/**
35-
* Subject that publishes the last and all subsequent events to each {@link Observer} that subscribes.
35+
* Subject that publishes the most recent and all subsequent events to each subscribed {@link Observer}.
36+
*
3637
* <p>
3738
* Example usage:
3839
* <p>
3940
* <pre> {@code
40-
41+
4142
// observer will receive all events.
4243
BehaviorSubject<Object> subject = BehaviorSubject.createWithDefaultValue("default");
4344
subject.subscribe(observer);
4445
subject.onNext("one");
4546
subject.onNext("two");
4647
subject.onNext("three");
47-
48-
// observer will receive the "one", "two" and "three" events.
48+
49+
// observer will receive the "one", "two" and "three" events, but not "zero"
4950
BehaviorSubject<Object> subject = BehaviorSubject.createWithDefaultValue("default");
51+
subject.onNext("zero");
5052
subject.onNext("one");
5153
subject.subscribe(observer);
5254
subject.onNext("two");
5355
subject.onNext("three");
54-
56+
5557
} </pre>
56-
*
58+
*
5759
* @param <T>
5860
*/
5961
public class BehaviorSubject<T> extends Subject<T, T> {
6062

6163
/**
62-
* Creates a {@link BehaviorSubject} which publishes the last and all subsequent events to each
64+
* Creates a {@link BehaviorSubject} which publishes the last and all subsequent events to each
6365
* {@link Observer} that subscribes to it.
64-
*
66+
*
6567
* @param defaultValue
66-
* The value which will be published to any {@link Observer} as long as the
68+
* The value which will be published to any {@link Observer} as long as the
6769
* {@link BehaviorSubject} has not yet received any events.
6870
* @return the constructed {@link BehaviorSubject}.
6971
*/
7072
public static <T> BehaviorSubject<T> createWithDefaultValue(T defaultValue) {
7173
final ConcurrentHashMap<Subscription, Observer<T>> observers = new ConcurrentHashMap<Subscription, Observer<T>>();
7274

7375
final AtomicReference<T> currentValue = new AtomicReference<T>(defaultValue);
74-
76+
7577
Func1<Observer<T>, Subscription> onSubscribe = new Func1<Observer<T>, Subscription>() {
7678
@Override
7779
public Subscription call(Observer<T> observer) {
@@ -104,7 +106,7 @@ protected BehaviorSubject(AtomicReference<T> currentValue, Func1<Observer<T>, Su
104106
this.currentValue = currentValue;
105107
this.observers = observers;
106108
}
107-
109+
108110
@Override
109111
public void onCompleted() {
110112
for (Observer<T> observer : observers.values()) {
@@ -224,7 +226,7 @@ private void assertErrorObserver(Observer<String> aObserver)
224226
verify(aObserver, times(1)).onNext("one");
225227
verify(aObserver, times(1)).onError(testException);
226228
}
227-
229+
228230
@Test
229231
public void testUnsubscribe()
230232
{

0 commit comments

Comments
 (0)