3.x: Improve Javadocs of Completable and some others (#6809)

Author: akarnokd

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

@@ -5261,7 +5261,7 @@ public final Iterable<T> blockingIterable() {
     @SchedulerSupport(SchedulerSupport.NONE)
     @NonNull
     public final Iterable<T> blockingIterable(int capacityHint) {
-        ObjectHelper.verifyPositive(capacityHint, "bufferSize");
+        ObjectHelper.verifyPositive(capacityHint, "capacityHint");
         return new BlockingObservableIterable<>(this, capacityHint);
     }
 

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

@@ -41,6 +41,7 @@ public interface Disposable {
      * executed exactly once when the {@code Disposable} is disposed.
      * @param run the Runnable to wrap
      * @return the new Disposable instance
+     * @throws NullPointerException if {@code run} is {@code null}
      * @since 3.0.0
      */
     @NonNull
@@ -52,14 +53,15 @@ static Disposable fromRunnable(@NonNull Runnable run) {
     /**
      * Construct a {@code Disposable} by wrapping a {@link Action} that is
      * executed exactly once when the {@code Disposable} is disposed.
-     * @param run the Action to wrap
+     * @param action the Action to wrap
      * @return the new Disposable instance
+     * @throws NullPointerException if {@code action} is {@code null}
      * @since 3.0.0
      */
     @NonNull
-    static Disposable fromAction(@NonNull Action run) {
-        Objects.requireNonNull(run, "run is null");
-        return new ActionDisposable(run);
+    static Disposable fromAction(@NonNull Action action) {
+        Objects.requireNonNull(action, "action is null");
+        return new ActionDisposable(action);
     }
 
     /**
@@ -69,6 +71,7 @@ static Disposable fromAction(@NonNull Action run) {
      * The {@code Future} is cancelled with {@code mayInterruptIfRunning == true}.
      * @param future the Future to wrap
      * @return the new Disposable instance
+     * @throws NullPointerException if {@code future} is {@code null}
      * @see #fromFuture(Future, boolean)
      * @since 3.0.0
      */
@@ -84,6 +87,7 @@ static Disposable fromFuture(@NonNull Future<?> future) {
      * @param future the Future to wrap
      * @param allowInterrupt if true, the future cancel happens via {@code Future.cancel(true)}
      * @return the new Disposable instance
+     * @throws NullPointerException if {@code future} is {@code null}
      * @since 3.0.0
      */
     @NonNull
@@ -97,6 +101,7 @@ static Disposable fromFuture(@NonNull Future<?> future, boolean allowInterrupt)
      * cancelled exactly once when the {@code Disposable} is disposed.
      * @param subscription the Runnable to wrap
      * @return the new Disposable instance
+     * @throws NullPointerException if {@code subscription} is {@code null}
      * @since 3.0.0
      */
     @NonNull
@@ -110,6 +115,7 @@ static Disposable fromSubscription(@NonNull Subscription subscription) {
      * closed exactly once when the {@code Disposable} is disposed.
      * @param autoCloseable the AutoCloseable to wrap
      * @return the new Disposable instance
+     * @throws NullPointerException if {@code autoCloseable} is {@code null}
      * @since 3.0.0
      */
     @NonNull
@@ -123,10 +129,12 @@ static Disposable fromAutoCloseable(@NonNull AutoCloseable autoCloseable) {
      * disposed when the returned {@code AutoCloseable} is closed.
      * @param disposable the Disposable instance
      * @return the new AutoCloseable instance
+     * @throws NullPointerException if {@code disposable} is {@code null}
      * @since 3.0.0
      */
     @NonNull
     static AutoCloseable toAutoCloseable(@NonNull Disposable disposable) {
+        Objects.requireNonNull(disposable, "disposable is null");
         return disposable::dispose;
     }
 

src/main/java/io/reactivex/rxjava3/disposables/Disposable.java

@@ -249,6 +249,8 @@ public final Flowable<T> refCount(int subscriberCount, long timeout, @NonNull Ti
      * @param unit the time unit of the timeout
      * @param scheduler the target scheduler to wait on before disconnecting
      * @return the new Flowable instance
+     * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
+     * @throws IllegalArgumentException if {@code subscriberCount} is non-positive
      * @since 2.2
      */
     @CheckReturnValue

src/main/java/io/reactivex/rxjava3/flowables/ConnectableFlowable.java

@@ -224,6 +224,8 @@ public final Observable<T> refCount(int subscriberCount, long timeout, @NonNull
      * @param unit the time unit of the timeout
      * @param scheduler the target scheduler to wait on before disconnecting
      * @return the new Observable instance
+     * @throws IllegalArgumentException if {@code subscriberCount} is non-positive
+     * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
      * @since 2.2
      */
     @CheckReturnValue

src/main/java/io/reactivex/rxjava3/observables/ConnectableObservable.java

@@ -204,6 +204,7 @@ public static <T> BehaviorProcessor<T> create() {
      *            the item that will be emitted first to any {@link Subscriber} as long as the
      *            {@link BehaviorProcessor} has not yet observed any items from its source {@code Observable}
      * @return the constructed {@link BehaviorProcessor}
+     * @throws NullPointerException if {@code defaultValue} is {@code null}
      */
     @CheckReturnValue
     @NonNull

src/main/java/io/reactivex/rxjava3/processors/BehaviorProcessor.java

@@ -192,10 +192,12 @@ public static <T> MulticastProcessor<T> create(boolean refCount) {
      * @param bufferSize the prefetch amount
      * @param <T> the input and output value type
      * @return the new MulticastProcessor instance
+     * @throws IllegalArgumentException if {@code bufferSize} is non-positive
      */
     @CheckReturnValue
     @NonNull
     public static <T> MulticastProcessor<T> create(int bufferSize) {
+        ObjectHelper.verifyPositive(bufferSize, "bufferSize");
         return new MulticastProcessor<>(bufferSize, false);
     }
 
@@ -207,10 +209,12 @@ public static <T> MulticastProcessor<T> create(int bufferSize) {
      * is cancelled
      * @param <T> the input and output value type
      * @return the new MulticastProcessor instance
+     * @throws IllegalArgumentException if {@code bufferSize} is non-positive
      */
     @CheckReturnValue
     @NonNull
     public static <T> MulticastProcessor<T> create(int bufferSize, boolean refCount) {
+        ObjectHelper.verifyPositive(bufferSize, "bufferSize");
         return new MulticastProcessor<>(bufferSize, refCount);
     }
 
@@ -223,7 +227,6 @@ public static <T> MulticastProcessor<T> create(int bufferSize, boolean refCount)
      */
     @SuppressWarnings("unchecked")
     MulticastProcessor(int bufferSize, boolean refCount) {
-        ObjectHelper.verifyPositive(bufferSize, "bufferSize");
         this.bufferSize = bufferSize;
         this.limit = bufferSize - (bufferSize >> 2);
         this.wip = new AtomicInteger();

src/main/java/io/reactivex/rxjava3/processors/MulticastProcessor.java

@@ -35,6 +35,11 @@ public void checkFlowable() throws Exception {
         checkSource("Flowable");
     }
 
+    @Test
+    public void checkCompletable() throws Exception {
+        checkSource("Completable");
+    }
+
     static void checkSource(String baseClassName) throws Exception {
         File f = TestHelper.findSource(baseClassName);
         if (f == null) {
@@ -346,15 +351,15 @@ static void blankRange(StringBuilder builder, int start, int end) {
 
             "Exception", "Throwable", "NullPointerException", "IllegalStateException", "IllegalArgumentException", "MissingBackpressureException", "UndeliverableException",
             "OutOfMemoryError", "StackOverflowError", "NoSuchElementException", "ClassCastException", "CompositeException",
-            "RuntimeException", "Error", "TimeoutException",
+            "RuntimeException", "Error", "TimeoutException", "OnErrorNotImplementedException",
 
             "false", "true", "onNext", "onError", "onComplete", "onSuccess", "onSubscribe", "null",
 
             "ConnectableFlowable", "ConnectableObservable", "Subject", "FlowableProcessor", "Processor", "Scheduler",
 
             "Optional", "CompletionStage", "Collector", "Collectors", "Schedulers", "RxJavaPlugins", "CompletableFuture",
 
-            "Object", "Integer", "Long", "Boolean", "LongConsumer",
+            "Object", "Integer", "Long", "Boolean", "LongConsumer", "BooleanSupplier",
 
             "GroupedFlowable", "GroupedObservable", "UnicastSubject", "UnicastProcessor",
 

src/test/java/io/reactivex/rxjava3/validators/JavadocCodesAndLinks.java

@@ -317,65 +317,7 @@ public void flowableDocRefersToFlowableTypes() throws Exception {
                     }
                 }
 
-                if (m.signature.matches("(?s).*?\\sSingle\\<.*?\\>\\s+\\w+\\(.*")) {
-                    for (String at : AT_RETURN_WORDS) {
-                        int idx = m.javadoc.indexOf(at + "{@code Flowable");
-                        if (idx >= 0) {
-                            e.append("Returns Single but docs return Flowable\r\n at io.reactivex.rxjava3.core.")
-                            .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                        idx = m.javadoc.indexOf(at + "{@code Maybe");
-                        if (idx >= 0) {
-                            e.append("Returns Single but docs return Maybe\r\n at io.reactivex.rxjava3.core.")
-                            .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                        idx = m.javadoc.indexOf(at + "{@code Publisher");
-                        if (idx >= 0) {
-                            e.append("Returns Single but docs return Publisher\r\n at io.reactivex.rxjava3.core.")
-                            .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                    }
-                }
-
-                if (m.signature.matches("(?s).*?\\sMaybe\\<.*\\>\\s+\\w+\\(.*")) {
-                    for (String at : AT_RETURN_WORDS) {
-                        int idx = m.javadoc.indexOf(at + "{@code Flowable");
-                        if (idx >= 0) {
-                            e.append("Returns Maybe but docs return Flowable\r\n at io.reactivex.rxjava3.core.")
-                            .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                        idx = m.javadoc.indexOf(at + "{@code Single");
-                        if (idx >= 0) {
-                            e.append("Returns Maybe but docs return Single\r\n at io.reactivex.rxjava3.core.")
-                            .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                        idx = m.javadoc.indexOf(at + "{@code Publisher");
-                        if (idx >= 0) {
-                            e.append("Returns Maybe but docs return Publisher\r\n at io.reactivex.rxjava3.core.")
-                            .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                    }
-                }
-
-                if (m.signature.matches("(?s).*?\\sCompletable\\s+\\w+\\(.*")) {
-                    for (String at : AT_RETURN_WORDS) {
-                        int idx = m.javadoc.indexOf(at + "{@code Flowable");
-                        if (idx >= 0) {
-                            e.append("Returns Completable but docs return Flowable\r\n at io.reactivex.rxjava3.core.")
-                            .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                        idx = m.javadoc.indexOf(at + "{@code Single");
-                        if (idx >= 0) {
-                            e.append("Returns Completable but docs return Single\r\n at io.reactivex.rxjava3.core.")
-                            .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                        idx = m.javadoc.indexOf(at + "{@code Maybe");
-                        if (idx >= 0) {
-                            e.append("Returns Completable but docs return Maybe\r\n at io.reactivex.rxjava3.core.")
-                            .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                    }
-                }
+                checkAtReturnAndSignatureMatch("Flowable", m, e, "Flowable", "Observable", "Maybe", "Single", "Completable");
 
                 aOrAn(e, m, "Flowable");
                 missingClosingDD(e, m, "Flowable");
@@ -478,55 +420,7 @@ public void observableDocRefersToObservableTypes() throws Exception {
                         break;
                     }
                 }
-                if (m.signature.matches("(?s).*?\\sSingle\\<.*?\\>\\s+\\w+\\(.*")) {
-                    for (String at : AT_RETURN_WORDS) {
-                        int idx = m.javadoc.indexOf(at + "{@code Observable");
-                        if (idx >= 0) {
-                            e.append("Returns Single but docs return Observable\r\n at io.reactivex.rxjava3.core.")
-                            .append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                        idx = m.javadoc.indexOf(at + "{@code Maybe");
-                        if (idx >= 0) {
-                            e.append("Returns Single but docs return Maybe\r\n at io.reactivex.rxjava3.core.")
-                            .append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                    }
-                }
-
-                if (m.signature.matches("(?s).*?\\sMaybe\\<.*?\\>\\s+\\w+\\(.*")) {
-                    for (String at : AT_RETURN_WORDS) {
-                        int idx = m.javadoc.indexOf(at + "{@code Observable");
-                        if (idx >= 0) {
-                            e.append("Returns Maybe but docs return Observable\r\n at io.reactivex.rxjava3.core.")
-                            .append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                        idx = m.javadoc.indexOf(at + "{@code Single");
-                        if (idx >= 0) {
-                            e.append("Returns Maybe but docs return Single\r\n at io.reactivex.rxjava3.core.")
-                            .append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                    }
-                }
-
-                if (m.signature.matches("(?s).*?\\sCompletable\\s+\\w+\\(.*")) {
-                    for (String at : AT_RETURN_WORDS) {
-                        int idx = m.javadoc.indexOf(at + "{@code Observable");
-                        if (idx >= 0) {
-                            e.append("Returns Completable but docs return Observable\r\n at io.reactivex.rxjava3.core.")
-                            .append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                        idx = m.javadoc.indexOf(at + "{@code Single");
-                        if (idx >= 0) {
-                            e.append("Returns Completable but docs return Single\r\n at io.reactivex.rxjava3.core.")
-                            .append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                        idx = m.javadoc.indexOf(at + "{@code Maybe");
-                        if (idx >= 0) {
-                            e.append("Returns Completable but docs return Maybe\r\n at io.reactivex.rxjava3.core.")
-                            .append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
-                        }
-                    }
-                }
+                checkAtReturnAndSignatureMatch("Observable", m, e, "Flowable", "Observable", "Maybe", "Single", "Completable");
 
                 aOrAn(e, m, "Observable");
                 missingClosingDD(e, m, "Observable");
@@ -890,6 +784,9 @@ public void completableDocRefersToCompletableTypes() throws Exception {
                         break;
                     }
                 }
+
+                checkAtReturnAndSignatureMatch("Completable", m, e, "Flowable", "Observable", "Maybe", "Single", "Completable");
+
                 aOrAn(e, m, "Completable");
                 missingClosingDD(e, m, "Completable");
                 backpressureMentionedWithoutAnnotation(e, m, "Completable");
@@ -903,6 +800,38 @@ public void completableDocRefersToCompletableTypes() throws Exception {
         }
     }
 
+    static void checkAtReturnAndSignatureMatch(String className, RxMethod m, StringBuilder e, String... types) {
+        for (String t : types) {
+            String regex;
+            if (t.contains("Completable")) {
+                regex = "(?s).*?\\s" + t + "\\s+\\w+\\(.*";
+            } else {
+                regex = "(?s).*?\\s" + t + "\\<.*?\\>\\s+\\w+\\(.*";
+            }
+            if (m.signature.matches(regex)) {
+                for (String at : AT_RETURN_WORDS) {
+                    for (String u : types) {
+                        if (!t.equals(u)) {
+                            int idx = m.javadoc.indexOf(at + "{@code " + u);
+                            if (idx >= 0) {
+                                e.append("Returns ").append(t)
+                                .append(" but docs return ")
+                                .append(u)
+                                .append("\r\n at io.reactivex.rxjava3.core.")
+                                .append(className)
+                                .append(".method(")
+                                .append(className)
+                                .append(".java:")
+                                .append(m.javadocLine + lineNumber(m.javadoc, idx) - 1)
+                                .append(")\r\n\r\n");
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     static void aOrAn(StringBuilder e, RxMethod m, String baseTypeName) {
         aOrAn(e, m, " an", "Single", baseTypeName);
         aOrAn(e, m, " an", "Maybe", baseTypeName);