Merge pull request ReactiveX#255 from jmhofer/fix-build-warnings

Cleaning up - fixing a lot of build warnings (mostly javadoc)

Author: benjchristensen

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

@@ -96,9 +96,9 @@ public boolean hasException() {
     }
 
     /**
-     * The kind of notification: OnNext, OnError, OnCompleted
+     * Retrieves the kind of the notification: OnNext, OnError, OnCompleted
      * 
-     * @return
+     * @return the kind of the notification: OnNext, OnError, OnCompleted
      */
     public Kind getKind() {
         return kind;

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

@@ -589,8 +589,8 @@ public void onNext(T args) {
      * <p>
      * This is similar to {@link #subscribe(Observer)} but blocks. Because it blocks it does not need the {@link Observer#onCompleted()} or {@link Observer#onError(Exception)} methods.
      * 
-     * @param onNext
-     *            {@link Action1}
+     * @param o
+     *            onNext {@link Action1 action}
      * @throws RuntimeException
      *             if error occurs
      */
@@ -901,7 +901,7 @@ public static <T> Observable<T> where(Observable<T> that, Func1<T, Boolean> pred
      * @param <T>
      *            the type of items in the {@link Iterable} sequence and the type emitted by the resulting Observable
      * @return an Observable that emits each item in the source {@link Iterable} sequence
-     * @see {@link #toObservable(Iterable)}
+     * @see #toObservable(Iterable)
      */
     public static <T> Observable<T> from(Iterable<T> iterable) {
         return toObservable(iterable);
@@ -915,7 +915,7 @@ public static <T> Observable<T> from(Iterable<T> iterable) {
      * @param <T>
      *            the type of items in the Array, and the type of items emitted by the resulting Observable
      * @return an Observable that emits each item in the source Array
-     * @see {@link #toObservable(Object...)}
+     * @see #toObservable(Object...)
      */
     public static <T> Observable<T> from(T... items) {
         return toObservable(items);
@@ -1219,7 +1219,7 @@ public R call(T t1) {
      * @return an Observable that emits a sequence that is the result of applying the transformation
      *         function to each item emitted by the source Observable and merging the results of
      *         the Observables obtained from this transformation
-     * @see {@link #flatMap(Observable, Func1)}
+     * @see #flatMap(Observable, Func1)
      */
     public static <T, R> Observable<R> mapMany(Observable<T> sequence, Func1<T, Observable<R>> func) {
         return create(OperationMap.mapMany(sequence, func));
@@ -1407,7 +1407,7 @@ public static <T> Observable<T> finallyDo(Observable<T> source, Action0 action)
      * @return an Observable that emits a sequence that is the result of applying the transformation
      *         function to each item emitted by the source Observable and merging the results of
      *         the Observables obtained from this transformation
-     * @see {@link #mapMany(Observable, Func1)}
+     * @see #mapMany(Observable, Func1)
      */
     public static <T, R> Observable<R> flatMap(Observable<T> sequence, Func1<T, Observable<R>> func) {
         return mapMany(sequence, func);
@@ -1435,7 +1435,7 @@ public static <T, R> Observable<R> flatMap(Observable<T> sequence, Func1<T, Obse
      * @return an Observable that emits a sequence that is the result of applying the transformation
      *         function to each item emitted by the source Observable and merging the results of
      *         the Observables obtained from this transformation
-     * @see {@link #mapMany(Observable, Func1)}
+     * @see #mapMany(Observable, Func1)
      */
     public static <T, R> Observable<R> flatMap(Observable<T> sequence, final Object func) {
         return mapMany(sequence, func);
@@ -2038,24 +2038,24 @@ public static <T> Observable<T> takeLast(final Observable<T> items, final int co
     }
 
     /**
-     * Returns a specified number of contiguous values from the start of an observable sequence.
+     * Returns the values from the start of an observable sequence while a given predicate remains true.
      * 
      * @param items
      * @param predicate
      *            a function to test each source element for a condition
-     * @return
+     * @return the values from the start of the given sequence 
      */
     public static <T> Observable<T> takeWhile(final Observable<T> items, Func1<T, Boolean> predicate) {
         return create(OperationTakeWhile.takeWhile(items, predicate));
     }
 
     /**
-     * Returns a specified number of contiguous values from the start of an observable sequence.
+     * Returns the values from the start of an observable sequence while a given predicate remains true.
      * 
      * @param items
      * @param predicate
      *            a function to test each source element for a condition
-     * @return
+     * @return the values from the start of the given sequence 
      */
     public static <T> Observable<T> takeWhile(final Observable<T> items, Object predicate) {
         @SuppressWarnings("rawtypes")
@@ -2075,7 +2075,7 @@ public Boolean call(T t) {
      * @param items
      * @param predicate
      *            a function to test each element for a condition; the second parameter of the function represents the index of the source element; otherwise, false.
-     * @return
+     * @return the values from the start of the given sequence 
      */
     public static <T> Observable<T> takeWhileWithIndex(final Observable<T> items, Func2<T, Integer, Boolean> predicate) {
         return create(OperationTakeWhile.takeWhileWithIndex(items, predicate));
@@ -2110,7 +2110,7 @@ public Observable<Timestamped<T>> timestamp() {
      * 
      * @param that
      *            the source Observable
-     * @returna Future that expects a single item emitted by the source Observable
+     * @return a Future that expects a single item emitted by the source Observable
      */
     public static <T> Future<T> toFuture(final Observable<T> that) {
         return OperationToFuture.toFuture(that);
@@ -2424,7 +2424,7 @@ public static <T> Observable<T> toObservable(T... items) {
      * @param sequence
      * @throws ClassCastException
      *             if T objects do not implement Comparable
-     * @return
+     * @return an observable containing the sorted list 
      */
     public static <T> Observable<List<T>> toSortedList(Observable<T> sequence) {
         return create(OperationToObservableSortedList.toSortedList(sequence));
@@ -2437,7 +2437,7 @@ public static <T> Observable<List<T>> toSortedList(Observable<T> sequence) {
      * 
      * @param sequence
      * @param sortFunction
-     * @return
+     * @return an observable containing the sorted list 
      */
     public static <T> Observable<List<T>> toSortedList(Observable<T> sequence, Func2<T, T, Integer> sortFunction) {
         return create(OperationToObservableSortedList.toSortedList(sequence, sortFunction));
@@ -2450,7 +2450,7 @@ public static <T> Observable<List<T>> toSortedList(Observable<T> sequence, Func2
      * 
      * @param sequence
      * @param sortFunction
-     * @return
+     * @return an observable containing the sorted list 
      */
     public static <T> Observable<List<T>> toSortedList(Observable<T> sequence, final Object sortFunction) {
         @SuppressWarnings("rawtypes")
@@ -2801,7 +2801,7 @@ public Boolean call(T t1) {
      * @return an Observable that emits a sequence that is the result of applying the transformation
      *         function to each item in the input sequence and merging the results of the
      *         Observables obtained from this transformation.
-     * @see {@link #mapMany(Func1)}
+     * @see #mapMany(Func1)
      */
     public <R> Observable<R> flatMap(Func1<T, Observable<R>> func) {
         return mapMany(func);
@@ -2822,7 +2822,7 @@ public <R> Observable<R> flatMap(Func1<T, Observable<R>> func) {
      * @return an Observable that emits a sequence that is the result of applying the transformation'
      *         function to each item in the input sequence and merging the results of the
      *         Observables obtained from this transformation.
-     * @see {@link #mapMany(Object)}
+     * @see #mapMany(Object)
      */
     public <R> Observable<R> flatMap(final Object callback) {
         return mapMany(callback);
@@ -2973,7 +2973,7 @@ public R call(T t1) {
      * @return an Observable that emits a sequence that is the result of applying the transformation
      *         function to each item in the input sequence and merging the results of the
      *         Observables obtained from this transformation.
-     * @see {@link #flatMap(Func1)}
+     * @see #flatMap(Func1)
      */
     public <R> Observable<R> mapMany(Func1<T, Observable<R>> func) {
         return mapMany(this, func);
@@ -2994,7 +2994,7 @@ public <R> Observable<R> mapMany(Func1<T, Observable<R>> func) {
      * @return an Observable that emits a sequence that is the result of applying the transformation'
      *         function to each item in the input sequence and merging the results of the
      *         Observables obtained from this transformation.
-     * @see {@link #flatMap(Object))}
+     * @see #flatMap(Object)
      */
     public <R> Observable<R> mapMany(final Object callback) {
         @SuppressWarnings("rawtypes")
@@ -3490,18 +3490,18 @@ public Observable<T> take(final int num) {
      * 
      * @param predicate
      *            a function to test each source element for a condition
-     * @return
+     * @return the values from the start of the given sequence 
      */
     public Observable<T> takeWhile(final Func1<T, Boolean> predicate) {
         return takeWhile(this, predicate);
     }
 
     /**
-     * Returns a specified number of contiguous values from the start of an observable sequence.
+     * Returns an Observable that items emitted by the source Observable as long as a specified condition is true.
      * 
      * @param predicate
      *            a function to test each source element for a condition
-     * @return
+     * @return the values from the start of the given sequence 
      */
     public Observable<T> takeWhile(final Object predicate) {
         return takeWhile(this, predicate);
@@ -3512,7 +3512,7 @@ public Observable<T> takeWhile(final Object predicate) {
      * 
      * @param predicate
      *            a function to test each element for a condition; the second parameter of the function represents the index of the source element; otherwise, false.
-     * @return
+     * @return the values from the start of the given sequence 
      */
     public Observable<T> takeWhileWithIndex(final Func2<T, Integer, Boolean> predicate) {
         return takeWhileWithIndex(this, predicate);
@@ -3523,7 +3523,7 @@ public Observable<T> takeWhileWithIndex(final Func2<T, Integer, Boolean> predica
      * 
      * @param predicate
      *            a function to test each element for a condition; the second parameter of the function represents the index of the source element; otherwise, false.
-     * @return
+     * @return the values from the start of the given sequence 
      */
     public Observable<T> takeWhileWithIndex(final Object predicate) {
         return takeWhileWithIndex(this, predicate);
@@ -3561,7 +3561,7 @@ public <E> Observable<T> takeUntil(Observable<E> other) {
      * <p>
      * This will throw an exception if the Observable emits more than 1 value. If more than 1 are expected then use <code>toList().toFuture()</code>.
      * 
-     * @returna Future that expects a single item emitted by the source Observable
+     * @return a Future that expects a single item emitted by the source Observable
      */
     public Future<T> toFuture() {
         return toFuture(this);
@@ -3594,7 +3594,7 @@ public Observable<List<T>> toList() {
      * 
      * @throws ClassCastException
      *             if T objects do not implement Comparable
-     * @return
+     * @return an observable containing the sorted list 
      */
     public Observable<List<T>> toSortedList() {
         return toSortedList(this);
@@ -3606,7 +3606,7 @@ public Observable<List<T>> toSortedList() {
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/toSortedList.png">
      * 
      * @param sortFunction
-     * @return
+     * @return an observable containing the sorted list 
      */
     public Observable<List<T>> toSortedList(Func2<T, T, Integer> sortFunction) {
         return toSortedList(this, sortFunction);
@@ -3618,7 +3618,7 @@ public Observable<List<T>> toSortedList(Func2<T, T, Integer> sortFunction) {
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/toSortedList.png">
      * 
      * @param sortFunction
-     * @return
+     * @return an observable containing the sorted list 
      */
     public Observable<List<T>> toSortedList(final Object sortFunction) {
         return toSortedList(this, sortFunction);
@@ -3705,7 +3705,7 @@ public Iterable<T> mostRecent(T initialValue) {
      * NOTE: If strong reasons for not depending on package names comes up then the implementation of this method can change to looking for a marker interface.
      * 
      * @param f
-     * @return
+     * @return {@code true} if the given function is an internal implementation, and {@code false} otherwise.
      */
     private boolean isInternalImplementation(Object o) {
         if (o == null) {

rxjava-core/src/main/java/rx/concurrency/SleepingAction.java

@@ -15,8 +15,6 @@
  */
 package rx.concurrency;
 
-import java.util.concurrent.TimeUnit;
-
 import rx.Scheduler;
 import rx.Subscription;
 import rx.util.functions.Func2;

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

@@ -23,7 +23,7 @@
 /**
  * An {@link Observable} that has been grouped by a key whose value can be obtained using {@link #getKey()} <p>
  * 
- * @see {@link Observable#groupBy(Observable, Func1)}
+ * @see Observable#groupBy(Observable, Func1)
  * 
  * @param <K>
  * @param <T>

rxjava-core/src/main/java/rx/operators/OperationDematerialize.java

@@ -28,7 +28,7 @@
 
 /**
  * Dematerializes the explicit notification values of an observable sequence as implicit notifications.
- * See http://msdn.microsoft.com/en-us/library/hh229047(v=vs.103).aspx for the Microsoft Rx equivalent.
+ * See <a href="http://msdn.microsoft.com/en-us/library/hh229047(v=vs.103).aspx">here</a> for the Microsoft Rx equivalent.
  */
 public final class OperationDematerialize {
 
@@ -38,7 +38,7 @@ public final class OperationDematerialize {
      * @param sequence
      *            An observable sequence containing explicit notification values which have to be turned into implicit notifications.
      * @return An observable sequence exhibiting the behavior corresponding to the source sequence's notification values.
-     * @see http://msdn.microsoft.com/en-us/library/hh229047(v=vs.103).aspx
+     * @see <a href="http://msdn.microsoft.com/en-us/library/hh229047(v=vs.103).aspx">Observable.Dematerialize(TSource) Method </a>
      */
     public static <T> Func1<Observer<T>, Subscription> dematerialize(final Observable<Notification<T>> sequence) {
         return new DematerializeObservable<T>(sequence);

rxjava-core/src/main/java/rx/operators/OperationFinally.java

@@ -15,7 +15,6 @@
  */
 package rx.operators;
 
-import static org.junit.Assert.*;
 import static org.mockito.Mockito.*;
 
 import org.junit.Before;
@@ -24,7 +23,6 @@
 import rx.Observable;
 import rx.Observer;
 import rx.Subscription;
-import rx.util.AtomicObservableSubscription;
 import rx.util.functions.Action0;
 import rx.util.functions.Func1;
 
@@ -103,19 +101,24 @@ public void onNext(T args) {
     public static class UnitTest {
         private Action0 aAction0;
         private Observer<String> aObserver;
+        
+        @SuppressWarnings("unchecked") // mocking has to be unchecked, unfortunately
         @Before
         public void before() {
             aAction0 = mock(Action0.class);
             aObserver = mock(Observer.class);
         }
+        
         private void checkActionCalled(Observable<String> input) {
             Observable.create(finallyDo(input, aAction0)).subscribe(aObserver);
             verify(aAction0, times(1)).call();
         }
+        
         @Test
         public void testFinallyCalledOnComplete() {
             checkActionCalled(Observable.toObservable(new String[] {"1", "2", "3"}));
         }
+        
         @Test
         public void testFinallyCalledOnError() {
             checkActionCalled(Observable.<String>error(new RuntimeException("expected")));

rxjava-core/src/main/java/rx/operators/OperationMaterialize.java

@@ -33,17 +33,17 @@
  * <p>
  * In other words, converts a sequence of OnNext, OnError and OnCompleted events into a sequence of ObservableNotifications containing the OnNext, OnError and OnCompleted values.
  * <p>
- * See http://msdn.microsoft.com/en-us/library/hh229453(v=VS.103).aspx for the Microsoft Rx equivalent.
+ * See <a href="http://msdn.microsoft.com/en-us/library/hh229453(v=VS.103).aspx">here</a> for the Microsoft Rx equivalent.
  */
 public final class OperationMaterialize {
 
     /**
      * Materializes the implicit notifications of an observable sequence as explicit notification values.
      * 
-     * @param source
+     * @param sequence
      *            An observable sequence of elements to project.
      * @return An observable sequence whose elements are the result of materializing the notifications of the given sequence.
-     * @see http://msdn.microsoft.com/en-us/library/hh229453(v=VS.103).aspx
+     * @see <a href="http://msdn.microsoft.com/en-us/library/hh229453(v=VS.103).aspx">Observable.Materialize(TSource) Method </a>
      */
     public static <T> Func1<Observer<Notification<T>>, Subscription> materialize(final Observable<T> sequence) {
         return new MaterializeObservable<T>(sequence);

rxjava-core/src/main/java/rx/operators/OperationMerge.java

@@ -44,10 +44,10 @@ public final class OperationMerge {
     /**
      * Flattens the observable sequences from the list of Observables into one observable sequence without any transformation.
      * 
-     * @param source
+     * @param o
      *            An observable sequence of elements to project.
      * @return An observable sequence whose elements are the result of flattening the output from the list of Observables.
-     * @see http://msdn.microsoft.com/en-us/library/hh229099(v=vs.103).aspx
+     * @see <a href="http://msdn.microsoft.com/en-us/library/hh229099(v=vs.103).aspx">Observable.Merge(TSource) Method (IObservable(TSource)[])</a>
      */
     public static <T> Func1<Observer<T>, Subscription> merge(final Observable<Observable<T>> o) {
         // wrap in a Func so that if a chain is built up, then asynchronously subscribed to twice we will have 2 instances of Take<T> rather than 1 handing both, which is not thread-safe.

rxjava-core/src/main/java/rx/operators/OperationMergeDelayError.java

@@ -51,10 +51,10 @@ public final class OperationMergeDelayError {
      * onError or onComplete so as to allow all successful
      * onNext calls to be received.
      * 
-     * @param source
+     * @param sequences
      *            An observable sequence of elements to project.
      * @return An observable sequence whose elements are the result of flattening the output from the list of Observables.
-     * @see http://msdn.microsoft.com/en-us/library/hh229099(v=vs.103).aspx
+     * @see <a href="http://msdn.microsoft.com/en-us/library/hh229099(v=vs.103).aspx">Observable.Merge(TSource) Method (IObservable(TSource)[])</a>
      */
     public static <T> Func1<Observer<T>, Subscription> mergeDelayError(final Observable<Observable<T>> sequences) {
         // wrap in a Func so that if a chain is built up, then asynchronously subscribed to twice we will have 2 instances of Take<T> rather than 1 handing both, which is not thread-safe.