Various Javadoc improvements and corrections.

Author: daveray

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

@@ -1,12 +1,12 @@
 /**
  * Copyright 2013 Netflix, Inc.
- * 
+ *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
+ *
  * http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -18,12 +18,12 @@
 /**
  * Provides a mechanism for receiving push-based notifications.
  * <p>
- * 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
- * well-behaved {@link Observable} will
+ * 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 well-behaved {@link Observable} will
  * call an Observer's <code>onCompleted</code> closure exactly once or the Observer's <code>onError</code> closure exactly once.
  * <p>
  * For more information see the <a href="https://github.com/Netflix/RxJava/wiki/Observable">RxJava Wiki</a>
- * 
+ *
  * @param <T>
  */
 public interface Observer<T> {
@@ -39,7 +39,7 @@ public interface Observer<T> {
      * Notifies the Observer that the {@link Observable} has experienced an error condition.
      * <p>
      * If the {@link Observable} calls this closure, it will not thereafter call <code>onNext</code> or <code>onCompleted</code>.
-     * 
+     *
      * @param e
      */
     public void onError(Exception e);
@@ -50,7 +50,7 @@ public interface Observer<T> {
      * 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.
      * <p>
      * The {@link Observable} will not call this closure again after it calls either <code>onCompleted</code> or <code>onError</code>.
-     * 
+     *
      * @param args
      */
     public void onNext(T args);

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

@@ -21,6 +21,8 @@
  * Subscription returns from {@link Observable#subscribe(Observer)} to allow unsubscribing.
  * <p>
  * See utilities in {@link Subscriptions} and implementations in the {@link rx.subscriptions} package.
+ * <p>
+ * This interface is the RxJava equivalent of {@code IDisposable} in Microsoft's Rx implementation.
  */
 public interface Subscription {
 

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

@@ -1,12 +1,12 @@
 /**
  * Copyright 2013 Netflix, Inc.
- * 
+ *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
+ *
  * http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -23,11 +23,11 @@
 /**
  * An {@link Observable} that has been grouped by a key whose value can be obtained using
  * {@link #getKey()} <p>
- * 
+ *
  * @see Observable#groupBy(Observable, Func1)
- * 
- * @param <K>
- * @param <T>
+ *
+ * @param <K> the type of the key
+ * @param <T> the type of the elements in the group
  */
 public class GroupedObservable<K, T> extends Observable<T> {
     private final K key;
@@ -37,8 +37,13 @@ public GroupedObservable(K key, Func1<Observer<T>, Subscription> onSubscribe) {
         this.key = key;
     }
 
+    /**
+     * Returns the key the elements in this observable were grouped by.
+     *
+     * @return the key the elements in this observable were grouped by
+     */
     public K getKey() {
         return key;
     }
-
 }
+

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

@@ -1,12 +1,12 @@
 /**
  * Copyright 2013 Netflix, Inc.
- * 
+ *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
+ *
  * http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -15,7 +15,7 @@
  */
 /**
  * <p>Rx Observables</p>
- * 
+ *
  * <p>A library that enables subscribing to and composing asynchronous events and
  * callbacks.</p>
  * <p>The Observable/Observer interfaces and associated operators (in
@@ -25,8 +25,8 @@
  * More information can be found at <a
  * href="http://msdn.microsoft.com/en-us/data/gg577609">http://msdn.microsoft.com/en-us/data/gg577609</a>.
  * </p>
- * 
- * 
+ *
+ *
  * <p>Compared with the Microsoft implementation:
  * <ul>
  * <li>Observable == IObservable</li>
@@ -37,9 +37,8 @@
  * </p>
  * <p>Services which intend on exposing data asynchronously and wish
  * to allow reactive processing and composition can implement the
- * Watchable interface which then allows Watchers to subscribe to them
+ * {@link rx.Observable} interface which then allows Observers to subscribe to them
  * and receive events.</p>
- * <p>Usage examples can be found on the Watchable and Watcher
- * classes.</p>
+ * <p>Usage examples can be found on the {@link rx.Observable} and {@link rx.Observer} classes.</p>
  */
-package rx;
+package rx;

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

@@ -1,12 +1,12 @@
 /**
  * Copyright 2013 Netflix, Inc.
- * 
+ *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
+ *
  * http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -32,33 +32,41 @@
 import rx.util.functions.Func1;
 
 /**
- * Subject that publishes only the last event to each {@link Observer} that has subscribed when the completes. 
+ * Subject that publishes only the last event to each {@link Observer} that has subscribed when the
+ * sequence completes.
+ *
  * <p>
  * Example usage:
  * <p>
  * <pre> {@code
- 
-  // observer will receive no onNext events.
+
+  // observer will receive no onNext events because the subject.onCompleted() isn't called.
   AsyncSubject<Object> subject = AsyncSubject.create();
   subject.subscribe(observer);
   subject.onNext("one");
   subject.onNext("two");
   subject.onNext("three");
- 
+
   // observer will receive "three" as the only onNext event.
   AsyncSubject<Object> subject = AsyncSubject.create();
   subject.subscribe(observer);
   subject.onNext("one");
   subject.onNext("two");
   subject.onNext("three");
   subject.onCompleted();
- 
+
   } </pre>
- * 
+ *
  * @param <T>
  */
 public class AsyncSubject<T> extends Subject<T, T> {
-	
+
+
+    /**
+     * Create a new AsyncSubject
+     *
+     * @return a new AsyncSubject
+     */
     public static <T> AsyncSubject<T> create() {
         final ConcurrentHashMap<Subscription, Observer<T>> observers = new ConcurrentHashMap<Subscription, Observer<T>>();
 
@@ -95,10 +103,10 @@ protected AsyncSubject(Func1<Observer<T>, Subscription> onSubscribe, ConcurrentH
 
     @Override
     public void onCompleted() {
-    	T finalValue = currentValue.get();
-    	for (Observer<T> observer : observers.values()) {
-			observer.onNext(finalValue);
-    	}
+        T finalValue = currentValue.get();
+        for (Observer<T> observer : observers.values()) {
+            observer.onNext(finalValue);
+        }
         for (Observer<T> observer : observers.values()) {
             observer.onCompleted();
         }
@@ -141,7 +149,7 @@ private void assertNeverCompletedObserver(Observer<String> aObserver)
             verify(aObserver, Mockito.never()).onError(testException);
             verify(aObserver, Mockito.never()).onCompleted();
         }
-        
+
         @Test
         public void testCompleted() {
         	AsyncSubject<Object> subject = AsyncSubject.create();
@@ -242,7 +250,7 @@ public void call(AsyncSubject<Object> DefaultSubject)
                 {
                     DefaultSubject.onError(new Exception());
                 }
-            }, 
+            },
             null);
         }
     }

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

@@ -1,12 +1,12 @@
 /**
  * Copyright 2013 Netflix, Inc.
- * 
+ *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
+ *
  * http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -32,46 +32,48 @@
 import rx.util.functions.Func1;
 
 /**
- * Subject that publishes the last and all subsequent events to each {@link Observer} that subscribes. 
+ * Subject that publishes the most recent and all subsequent events to each subscribed {@link Observer}.
+ *
  * <p>
  * Example usage:
  * <p>
  * <pre> {@code
- 
+
   // observer will receive all events.
   BehaviorSubject<Object> subject = BehaviorSubject.createWithDefaultValue("default");
   subject.subscribe(observer);
   subject.onNext("one");
   subject.onNext("two");
   subject.onNext("three");
- 
-  // observer will receive the "one", "two" and "three" events.
+
+  // observer will receive the "one", "two" and "three" events, but not "zero"
   BehaviorSubject<Object> subject = BehaviorSubject.createWithDefaultValue("default");
+  subject.onNext("zero");
   subject.onNext("one");
   subject.subscribe(observer);
   subject.onNext("two");
   subject.onNext("three");
- 
+
   } </pre>
- * 
+ *
  * @param <T>
  */
 public class BehaviorSubject<T> extends Subject<T, T> {
 
     /**
-     * Creates a {@link BehaviorSubject} which publishes the last and all subsequent events to each 
+     * Creates a {@link BehaviorSubject} which publishes the last and all subsequent events to each
      * {@link Observer} that subscribes to it.
-     *  
+     *
      * @param defaultValue
-     *            The value which will be published to any {@link Observer} as long as the 
+     *            The value which will be published to any {@link Observer} as long as the
      *            {@link BehaviorSubject} has not yet received any events.
      * @return the constructed {@link BehaviorSubject}.
      */
     public static <T> BehaviorSubject<T> createWithDefaultValue(T defaultValue) {
         final ConcurrentHashMap<Subscription, Observer<T>> observers = new ConcurrentHashMap<Subscription, Observer<T>>();
 
         final AtomicReference<T> currentValue = new AtomicReference<T>(defaultValue);
-        
+
         Func1<Observer<T>, Subscription> onSubscribe = new Func1<Observer<T>, Subscription>() {
             @Override
             public Subscription call(Observer<T> observer) {
@@ -104,7 +106,7 @@ protected BehaviorSubject(AtomicReference<T> currentValue, Func1<Observer<T>, Su
         this.currentValue = currentValue;
         this.observers = observers;
     }
-    
+
     @Override
     public void onCompleted() {
         for (Observer<T> observer : observers.values()) {
@@ -224,7 +226,7 @@ private void assertErrorObserver(Observer<String> aObserver)
             verify(aObserver, times(1)).onNext("one");
             verify(aObserver, times(1)).onError(testException);
         }
-        
+
         @Test
         public void testUnsubscribe()
         {