Improve doOnDispose JavaDoc (#5296)

* correct javadoc note in Observable.doOnDispose()

The note was claiming Observable.doOnDispose() would be called for
terminal events of the Observable, which is not the case

* small improvement to .doOnDispose javadocs to refer to Actions

* add @throws mentions to doOnDisposed javadocs

Author: Mauin

src/main/java/io/reactivex/Completable.java

@@ -1107,13 +1107,13 @@ public final Completable doOnComplete(Action onComplete) {
     }
 
     /**
-     * Returns a Completable which calls the given onDispose callback if the child subscriber cancels
-     * the subscription.
+     * Calls the shared {@code Action} if a CompletableObserver subscribed to the current
+     * Completable disposes the common Disposable it received via onSubscribe.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code doOnDispose} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
-     * @param onDispose the callback to call when the child subscriber disposes the subscription
+     * @param onDispose the action to call when the child subscriber disposes the subscription
      * @return the new Completable instance
      * @throws NullPointerException if onDispose is null
      */

src/main/java/io/reactivex/Maybe.java

@@ -2441,13 +2441,14 @@ public final Maybe<T> doFinally(Action onFinally) {
     }
 
     /**
-     * Calls the shared runnable if a MaybeObserver subscribed to the current Maybe
+     * Calls the shared {@code Action} if a MaybeObserver subscribed to the current Maybe
      * disposes the common Disposable it received via onSubscribe.
      * <dl>
      * <dt><b>Scheduler:</b></dt>
      * <dd>{@code doOnDispose} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
-     * @param onDispose the runnable called when the subscription is cancelled (disposed)
+     * @param onDispose the action called when the subscription is cancelled (disposed)
+     * @throws NullPointerException if onDispose is null
      * @return the new Maybe instance
      */
     @CheckReturnValue

src/main/java/io/reactivex/Observable.java

@@ -6895,8 +6895,6 @@ public final Observable<T> doFinally(Action onFinally) {
      * If the action throws a runtime exception, that exception is rethrown by the {@code dispose()} call,
      * sometimes as a {@code CompositeException} if there were multiple exceptions along the way.
      * <p>
-     * Note that terminal events trigger the action unless the {@code ObservableSource} is subscribed to via {@code unsafeSubscribe()}.
-     * <p>
      * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnUnsubscribe.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
@@ -6906,6 +6904,7 @@ public final Observable<T> doFinally(Action onFinally) {
      * @param onDispose
      *            the action that gets called when the source {@code ObservableSource}'s Disposable is disposed
      * @return the source {@code ObservableSource} modified so as to call this Action when appropriate
+     * @throws NullPointerException if onDispose is null
      * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
      */
     @CheckReturnValue

src/main/java/io/reactivex/Single.java

@@ -1926,14 +1926,15 @@ public final Single<T> doOnError(final Consumer<? super Throwable> onError) {
     }
 
     /**
-     * Calls the shared runnable if a SingleObserver subscribed to the current Single
+     * Calls the shared {@code Action} if a SingleObserver subscribed to the current Single
      * disposes the common Disposable it received via onSubscribe.
      * <dl>
      * <dt><b>Scheduler:</b></dt>
      * <dd>{@code doOnDispose} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
-     * @param onDispose the runnable called when the subscription is disposed
+     * @param onDispose the action called when the subscription is disposed
      * @return the new Single instance
+     * @throws NullPointerException if onDispose is null
      * @since 2.0
      */
     @CheckReturnValue