Adding missing javadocs to Exceptions/OnErrorThrowable (#1322)

Author: DavidMGross

rxjava-core/src/main/java/rx/exceptions/Exceptions.java

@@ -49,7 +49,24 @@ public static RuntimeException propagate(Throwable t) {
     }
 
     /**
-     * @warn javadoc missing
+     * Throws a particular {@code Throwable} only if it belongs to a set of "fatal" error varieties. These
+     * varieties are as follows:
+     * <ul>
+     * <li>{@link OnErrorNotImplementedException}</li>
+     * <li>{@link OnErrorFailedException}</li>
+     * <li>{@code StackOverflowError}</li>
+     * <li>{@code VirtualMachineError}</li>
+     * <li>{@code ThreadDeath}</li>
+     * <li>{@code LinkageError}</li>
+     * </ul>
+     * This can be useful if you are writing an operator that calls user-supplied code, and you want to
+     * notify subscribers of errors encountered in that code by calling their {@code onError} methods, but only
+     * if the errors are not so catastrophic that such a call would be futile, in which case you simply want to
+     * rethrow the error.
+     *
+     * @param t
+     *         the {@code Throwable} to test and perhaps throw
+     * @see <a href="https://github.com/Netflix/RxJava/issues/748#issuecomment-32471495">RxJava: StackOverflowError is swallowed (Issue #748)</a>
      */
     public static void throwIfFatal(Throwable t) {
         if (t instanceof OnErrorNotImplementedException) {
@@ -77,7 +94,13 @@ else if (t instanceof StackOverflowError) {
     private static final int MAX_DEPTH = 25;
 
     /**
-     * @warn javadoc missing
+     * Adds a {@code Throwable} to a causality-chain of Throwables, as an additional cause (if it does not
+     * already appear in the chain among the causes).
+     *
+     * @param e
+     *         the {@code Throwable} at the head of the causality chain
+     * @param cause
+     *         the {@code Throwable} you want to add as a cause of the chain
      */
     public static void addCause(Throwable e, Throwable cause) {
         Set<Throwable> seenCauses = new HashSet<Throwable>();
@@ -106,8 +129,12 @@ public static void addCause(Throwable e, Throwable cause) {
     }
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Get the {@code Throwable} at the end of the causality-chain for a particular {@code Throwable}
+     *
+     * @param e
+     *         the {@code Throwable} whose final cause you are curious about
+     * @return the last {@code Throwable} in the causality-chain of {@code e} (or a "Stack too deep to get
+     *         final cause" {@code RuntimeException} if the chain is too long to traverse)
      */
     public static Throwable getFinalCause(Throwable e) {
         int i = 0;

rxjava-core/src/main/java/rx/exceptions/OnErrorThrowable.java

@@ -16,7 +16,10 @@
 package rx.exceptions;
 
 /**
- * @warn javadoc class description missing
+ * Represents a {@code Throwable} that an {@code Observable} might notify its subscribers of, but that then can
+ * be handled by an operator that is designed to recover from or react appropriately to such an error. You can
+ * recover more information from an {@code OnErrorThrowable} than is found in a typical {@code Throwable}, such
+ * as the item the {@code Observable} was trying to emit at the time the error was encountered.
  */
 public class OnErrorThrowable extends RuntimeException {
 
@@ -38,8 +41,9 @@ private OnErrorThrowable(Throwable exception, Object value) {
     }
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Get the value associated with this {@code OnErrorThrowable}
+     *
+     * @return the value associated with this {@code OnErrorThrowable} (or {@code null} if there is none)
      */
     public Object getValue() {
         return value;
@@ -72,13 +76,13 @@ public static OnErrorThrowable from(Throwable t) {
     }
 
     /**
-     * Adds the given value as the final cause of the given {@code Throwable} wrapped in
-     * {@code OnNextValue}/{@code RuntimeException}.
+     * Adds the given item as the final cause of the given {@code Throwable}, wrapped in {@code OnNextValue}
+     * (which extends {@code RuntimeException}).
      * 
      * @param e
      *          the {@link Throwable} to which you want to add a cause
      * @param value
-     *          the cause you want to add to {@code e}
+     *          the item you want to add to {@code e} as the cause of the {@code Throwable}
      * @return the same {@code Throwable} ({@code e}) that was passed in, with {@code value} added to it as a
      *         cause
      */
@@ -96,24 +100,30 @@ public static Throwable addValueAsLastCause(Throwable e, Object value) {
     }
 
     /**
-     * @warn javadoc class description missing
+     * Represents an exception that was encountered while trying to emit an item from an Observable, and
+     * tries to preserve that item for future use and/or reporting.
      */
     public static class OnNextValue extends RuntimeException {
 
         private static final long serialVersionUID = -3454462756050397899L;
         private final Object value;
 
         /**
-         * @warn javadoc missing
+         * Create an {@code OnNextValue} exception and include in its error message a string representation of
+         * the item that was intended to be emitted at the time the exception was handled.
+         *
+         * @param value
+         *         the item that the Observable was trying to emit at the time of the exception
          */
         public OnNextValue(Object value) {
             super("OnError while emitting onNext value: " + value);
             this.value = value;
         }
 
         /**
-         * @warn javadoc missing
-         * @return
+         * Retrieve the item that the Observable was trying to emit at the time this exception occurred.
+         *
+         * @return the item that the Observable was trying to emit at the time of the exception
          */
         public Object getValue() {
             return value;