3.x: Cleanup and prettify Javadocs, widen XOperator throws (#6785)

* 3.x: Cleanup and prettify Javadocs, widen XOperator throws

* Fix encoding of § in javadoc

* Fix a wrong tag name

Author: akarnokd

Diff for: src/main/java/io/reactivex/rxjava3/annotations/BackpressureKind.java

@@ -32,13 +32,13 @@ public enum BackpressureKind {
      */
     SPECIAL,
     /**
-     * The operator requests Long.MAX_VALUE from upstream but respects the backpressure
+     * The operator requests {@link Long#MAX_VALUE} from upstream but respects the backpressure
      * of the downstream.
      */
     UNBOUNDED_IN,
     /**
-     * The operator will emit a MissingBackpressureException if the downstream didn't request
-     * enough or in time.
+     * The operator will emit a {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException MissingBackpressureException}
+     * if the downstream didn't request enough or in time.
      */
     ERROR,
     /**

Diff for: src/main/java/io/reactivex/rxjava3/core/BackpressureOverflowStrategy.java

@@ -19,7 +19,10 @@
  * Options to deal with buffer overflow when using onBackpressureBuffer.
  */
 public enum BackpressureOverflowStrategy {
-    /** Signal a MissingBackpressureException and terminate the sequence. */
+    /**
+     * Signal a {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException MissingBackpressureException}
+     * and terminate the sequence.
+     */
     ERROR,
     /** Drop the oldest value from the buffer. */
     DROP_OLDEST,

Diff for: src/main/java/io/reactivex/rxjava3/core/BackpressureStrategy.java

@@ -18,25 +18,26 @@
  */
 public enum BackpressureStrategy {
     /**
-     * OnNext events are written without any buffering or dropping.
+     * The {@code onNext} events are written without any buffering or dropping.
      * Downstream has to deal with any overflow.
      * <p>Useful when one applies one of the custom-parameter onBackpressureXXX operators.
      */
     MISSING,
     /**
-     * Signals a MissingBackpressureException in case the downstream can't keep up.
+     * Signals a {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException MissingBackpressureException}
+     * in case the downstream can't keep up.
      */
     ERROR,
     /**
-     * Buffers <em>all</em> onNext values until the downstream consumes it.
+     * Buffers <em>all</em> {@code onNext} values until the downstream consumes it.
      */
     BUFFER,
     /**
-     * Drops the most recent onNext value if the downstream can't keep up.
+     * Drops the most recent {@code onNext} value if the downstream can't keep up.
      */
     DROP,
     /**
-     * Keeps only the latest onNext value, overwriting any previous value if the
+     * Keeps only the latest {@code onNext} value, overwriting any previous value if the
      * downstream can't keep up.
      */
     LATEST

Diff for: src/main/java/io/reactivex/rxjava3/core/CompletableEmitter.java

@@ -82,12 +82,12 @@ public interface CompletableEmitter {
     boolean isDisposed();
 
     /**
-     * Attempts to emit the specified {@code Throwable} error if the downstream
+     * Attempts to emit the specified {@link Throwable} error if the downstream
      * hasn't cancelled the sequence or is otherwise terminated, returning false
      * if the emission is not allowed to happen due to lifecycle restrictions.
      * <p>
-     * Unlike {@link #onError(Throwable)}, the {@code RxJavaPlugins.onError} is not called
-     * if the error could not be delivered.
+     * Unlike {@link #onError(Throwable)}, the {@link io.reactivex.rxjava3.plugins.RxJavaPlugins#onError(Throwable) RxjavaPlugins.onError}
+     * is not called if the error could not be delivered.
      * <p>History: 2.1.1 - experimental
      * @param t the throwable error to signal if possible
      * @return true if successful, false if the downstream is not able to accept further

Diff for: src/main/java/io/reactivex/rxjava3/core/CompletableObserver.java

@@ -49,9 +49,9 @@
  */
 public interface CompletableObserver {
     /**
-     * Called once by the Completable to set a Disposable on this instance which
+     * Called once by the {@link Completable} to set a {@link Disposable} on this instance which
      * then can be used to cancel the subscription at any time.
-     * @param d the Disposable instance to call dispose on for cancellation, not null
+     * @param d the {@code Disposable} instance to call dispose on for cancellation, not null
      */
     void onSubscribe(@NonNull Disposable d);
 
@@ -62,7 +62,7 @@ public interface CompletableObserver {
 
     /**
      * Called once if the deferred computation 'throws' an exception.
-     * @param e the exception, not null.
+     * @param e the exception, not {@code null}.
      */
     void onError(@NonNull Throwable e);
 }

Diff for: src/main/java/io/reactivex/rxjava3/core/CompletableOnSubscribe.java

@@ -23,8 +23,8 @@
 public interface CompletableOnSubscribe {
 
     /**
-     * Called for each CompletableObserver that subscribes.
-     * @param emitter the safe emitter instance, never null
+     * Called for each {@link CompletableObserver} that subscribes.
+     * @param emitter the safe emitter instance, never {@code null}
      * @throws Throwable on error
      */
     void subscribe(@NonNull CompletableEmitter emitter) throws Throwable;

Diff for: src/main/java/io/reactivex/rxjava3/core/CompletableOperator.java

@@ -21,11 +21,11 @@
 @FunctionalInterface
 public interface CompletableOperator {
     /**
-     * Applies a function to the child CompletableObserver and returns a new parent CompletableObserver.
-     * @param observer the child CompletableObservable instance
-     * @return the parent CompletableObserver instance
-     * @throws Exception on failure
+     * Applies a function to the child {@link CompletableObserver} and returns a new parent {@code CompletableObserver}.
+     * @param observer the child {@code CompletableObserver} instance
+     * @return the parent {@code CompletableObserver} instance
+     * @throws Throwable on failure
      */
     @NonNull
-    CompletableObserver apply(@NonNull CompletableObserver observer) throws Exception;
+    CompletableObserver apply(@NonNull CompletableObserver observer) throws Throwable;
 }

Diff for: src/main/java/io/reactivex/rxjava3/core/CompletableSource.java

@@ -24,9 +24,9 @@
 public interface CompletableSource {
 
     /**
-     * Subscribes the given CompletableObserver to this CompletableSource instance.
-     * @param co the CompletableObserver, not null
-     * @throws NullPointerException if {@code co} is null
+     * Subscribes the given {@link CompletableObserver} to this {@code CompletableSource} instance.
+     * @param observer the {@code CompletableObserver}, not {@code null}
+     * @throws NullPointerException if {@code observer} is {@code null}
      */
-    void subscribe(@NonNull CompletableObserver co);
+    void subscribe(@NonNull CompletableObserver observer);
 }

Diff for: src/main/java/io/reactivex/rxjava3/core/CompletableTransformer.java

@@ -16,15 +16,15 @@
 import io.reactivex.rxjava3.annotations.NonNull;
 
 /**
- * Convenience interface and callback used by the compose operator to turn a Completable into another
- * Completable fluently.
+ * Convenience interface and callback used by the compose operator to turn a {@link Completable} into another
+ * {@code Completable} fluently.
  */
 @FunctionalInterface
 public interface CompletableTransformer {
     /**
-     * Applies a function to the upstream Completable and returns a CompletableSource.
-     * @param upstream the upstream Completable instance
-     * @return the transformed CompletableSource instance
+     * Applies a function to the upstream {@link Completable} and returns a {@link CompletableSource}.
+     * @param upstream the upstream {@code Completable} instance
+     * @return the transformed {@code CompletableSource} instance
      */
     @NonNull
     CompletableSource apply(@NonNull Completable upstream);

Diff for: src/main/java/io/reactivex/rxjava3/core/Emitter.java

@@ -29,13 +29,13 @@ public interface Emitter<T> {
 
     /**
      * Signal a normal value.
-     * @param value the value to signal, not null
+     * @param value the value to signal, not {@code null}
      */
     void onNext(@NonNull T value);
 
     /**
-     * Signal a Throwable exception.
-     * @param error the Throwable to signal, not null
+     * Signal a {@link Throwable} exception.
+     * @param error the {@code Throwable} to signal, not {@code null}
      */
     void onError(@NonNull Throwable error);