1.x: javac- and javadoc-related cleanup in components, part 1 (#3949)

Author: akarnokd

src/main/java/rx/BackpressureOverflow.java

@@ -37,11 +37,11 @@ public interface Strategy {
     }
 
     public static final BackpressureOverflow.Strategy ON_OVERFLOW_DEFAULT = Error.INSTANCE;
-    @SuppressWarnings("unused")
+
     public static final BackpressureOverflow.Strategy ON_OVERFLOW_ERROR = Error.INSTANCE;
-    @SuppressWarnings("unused")
+
     public static final BackpressureOverflow.Strategy ON_OVERFLOW_DROP_OLDEST = DropOldest.INSTANCE;
-    @SuppressWarnings("unused")
+
     public static final BackpressureOverflow.Strategy ON_OVERFLOW_DROP_LATEST = DropLatest.INSTANCE;
 
     /**

src/main/java/rx/Observable.java

@@ -116,6 +116,7 @@ public static <T> Observable<T> create(OnSubscribe<T> f) {
      * 
      * @param <T>
      *            the type of the items that this Observable emits
+     * @param <S> the state type
      * @param syncOnSubscribe
      *            an implementation of {@link SyncOnSubscribe}. There are many static creation methods 
      *            on the class for convenience.  
@@ -151,6 +152,7 @@ public static <S, T> Observable<T> create(SyncOnSubscribe<S, T> syncOnSubscribe)
      * 
      * @param <T>
      *            the type of the items that this Observable emits
+     * @param <S> the state type
      * @param asyncOnSubscribe
      *            an implementation of {@link AsyncOnSubscribe}. There are many static creation methods 
      *            on the class for convenience. 
@@ -167,13 +169,16 @@ public static <S, T> Observable<T> create(AsyncOnSubscribe<S, T> asyncOnSubscrib
 
     /**
      * Invoked when Observable.subscribe is called.
+     * @param <T> the output value type
      */
     public interface OnSubscribe<T> extends Action1<Subscriber<? super T>> {
         // cover for generics insanity
     }
 
     /**
      * Operator function for lifting into an Observable.
+     * @param <T> the upstream's value type (input)
+     * @param <R> the downstream's value type (output)
      */
     public interface Operator<R, T> extends Func1<Subscriber<? super R>, Subscriber<? super T>> {
         // cover for generics insanity

src/main/java/rx/Single.java

@@ -135,6 +135,7 @@ public static <T> Single<T> create(OnSubscribe<T> f) {
 
     /**
      * Invoked when Single.execute is called.
+     * @param <T> the output value type
      */
     public interface OnSubscribe<T> extends Action1<SingleSubscriber<? super T>> {
         // cover for generics insanity
@@ -157,6 +158,7 @@ public interface OnSubscribe<T> extends Action1<SingleSubscriber<? super T>> {
      * <dd>{@code lift} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
      * 
+     * @param <R> the downstream's value type (output)
      * @param lift
      *            the Operator that implements the Single-operating function to be applied to the source Single
      * @return a Single that is the result of applying the lifted Operator to the source Single
@@ -657,12 +659,14 @@ public static <T> Single<T> just(final T value) {
      * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
      *
+     * @param <T> the value type of the sources and the output
      * @param source
      *            a {@code Single} that emits a {@code Single}
      * @return a {@code Single} that emits the item that is the result of flattening the {@code Single} emitted
      *         by {@code source}
      * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
      */
+    @SuppressWarnings({ "unchecked", "rawtypes" })
     public static <T> Single<T> merge(final Single<? extends Single<? extends T>> source) {
         if (source instanceof ScalarSynchronousSingle) {
             return ((ScalarSynchronousSingle<T>) source).scalarFlatMap((Func1) UtilityFunctions.identity());

src/main/java/rx/exceptions/CompositeException.java

@@ -41,7 +41,11 @@ public final class CompositeException extends RuntimeException {
     private final List<Throwable> exceptions;
     private final String message;
 
-    /** @deprecated please use {@link #CompositeException(Collection)} */
+    /** 
+     * Constructs a CompositeException with the given prefix and error collection.
+     * @param messagePrefix the prefix to use (actually unused)
+     * @param errors the collection of errors
+     * @deprecated please use {@link #CompositeException(Collection)} */
     @Deprecated
     public CompositeException(String messagePrefix, Collection<? extends Throwable> errors) {
         Set<Throwable> deDupedExceptions = new LinkedHashSet<Throwable>();

src/main/java/rx/exceptions/OnCompletedFailedException.java

@@ -27,7 +27,7 @@ public final class OnCompletedFailedException extends RuntimeException {
     /**
      * Wraps the {@code Throwable} before it is to be re-thrown as an {@code OnCompletedFailedException}.
      *
-     * @param e
+     * @param throwable
      *          the {@code Throwable} to re-throw; if null, a NullPointerException is constructed
      */
     public OnCompletedFailedException(Throwable throwable) {
@@ -40,7 +40,7 @@ public OnCompletedFailedException(Throwable throwable) {
      *
      * @param message
      *          the message to assign to the {@code Throwable} to re-throw
-     * @param e
+     * @param throwable
      *          the {@code Throwable} to re-throw; if null, a NullPointerException is constructed
      */
     public OnCompletedFailedException(String message, Throwable throwable) {

src/main/java/rx/functions/Action1.java

@@ -17,6 +17,7 @@
 
 /**
  * A one-argument action.
+ * @param <T> the first argument type
  */
 public interface Action1<T> extends Action {
     void call(T t);

src/main/java/rx/functions/Action2.java

@@ -17,6 +17,8 @@
 
 /**
  * A two-argument action.
+ * @param <T1> the first argument type
+ * @param <T2> the second argument type
  */
 public interface Action2<T1, T2> extends Action {
     void call(T1 t1, T2 t2);

src/main/java/rx/functions/Action3.java

@@ -17,6 +17,9 @@
 
 /**
  * A three-argument action.
+ * @param <T1> the first argument type
+ * @param <T2> the second argument type
+ * @param <T3> the third argument type
  */
 public interface Action3<T1, T2, T3> extends Action {
     void call(T1 t1, T2 t2, T3 t3);

src/main/java/rx/functions/Action4.java

@@ -18,6 +18,10 @@
 
 /**
  * A four-argument action.
+ * @param <T1> the first argument type
+ * @param <T2> the second argument type
+ * @param <T3> the third argument type
+ * @param <T4> the fourth argument type
  */
 public interface Action4<T1, T2, T3, T4> extends Action {
     void call(T1 t1, T2 t2, T3 t3, T4 t4);

src/main/java/rx/functions/Action5.java

@@ -18,6 +18,11 @@
 
 /**
  * A five-argument action.
+ * @param <T1> the first argument type
+ * @param <T2> the second argument type
+ * @param <T3> the third argument type
+ * @param <T4> the fourth argument type
+ * @param <T5> the fifth argument type
  */
 public interface Action5<T1, T2, T3, T4, T5> extends Action {
     void call(T1 t1, T2 t2, T3 t3, T4 t4, T5 t5);

src/main/java/rx/functions/Action6.java

@@ -18,6 +18,12 @@
 
 /**
  * A six-argument action.
+ * @param <T1> the first argument type
+ * @param <T2> the second argument type
+ * @param <T3> the third argument type
+ * @param <T4> the fourth argument type
+ * @param <T5> the fifth argument type
+ * @param <T6> the sixth argument type
  */
 public interface Action6<T1, T2, T3, T4, T5, T6> extends Action {
     void call(T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6);

src/main/java/rx/functions/Action7.java

@@ -17,6 +17,13 @@
 
 /**
  * A seven-argument action.
+ * @param <T1> the first argument type
+ * @param <T2> the second argument type
+ * @param <T3> the third argument type
+ * @param <T4> the fourth argument type
+ * @param <T5> the fifth argument type
+ * @param <T6> the sixth argument type
+ * @param <T7> the seventh argument type
  */
 public interface Action7<T1, T2, T3, T4, T5, T6, T7> extends Action {
     void call(T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7);

src/main/java/rx/functions/Action8.java

@@ -17,6 +17,14 @@
 
 /**
  * An eight-argument action.
+ * @param <T1> the first argument type
+ * @param <T2> the second argument type
+ * @param <T3> the third argument type
+ * @param <T4> the fourth argument type
+ * @param <T5> the fifth argument type
+ * @param <T6> the sixth argument type
+ * @param <T7> the seventh argument type
+ * @param <T8> the eigth argument type
  */
 public interface Action8<T1, T2, T3, T4, T5, T6, T7, T8> extends Action {
     void call(T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8);

src/main/java/rx/functions/Action9.java

@@ -17,6 +17,15 @@
 
 /**
  * A nine-argument action.
+ * @param <T1> the first argument type
+ * @param <T2> the second argument type
+ * @param <T3> the third argument type
+ * @param <T4> the fourth argument type
+ * @param <T5> the fifth argument type
+ * @param <T6> the sixth argument type
+ * @param <T7> the seventh argument type
+ * @param <T8> the eigth argument type
+ * @param <T9> the ninth argument type
  */
 public interface Action9<T1, T2, T3, T4, T5, T6, T7, T8, T9> extends Action {
     void call(T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9);