4.x: Hide documentation in sealed interfaces [1/x]

akarnokd · akarnokd · commit 3148e037cac3 · 2026-03-19T09:59:34.000+01:00
This should reduce the file size of the main classes while also keeping
docks in IDEs.
diff --git a/src/main/java/io/reactivex/rxjava4/core/Flowable.java b/src/main/java/io/reactivex/rxjava4/core/Flowable.java
@@ -19,6 +19,7 @@
 import java.util.stream.*;
 
 import io.reactivex.rxjava4.annotations.*;
+import io.reactivex.rxjava4.core.docs.FlowableDocBasic;
 import io.reactivex.rxjava4.disposables.*;
 import io.reactivex.rxjava4.exceptions.*;
 import io.reactivex.rxjava4.flowables.*;
@@ -153,7 +154,9 @@
  * @see ParallelFlowable
  * @see io.reactivex.rxjava4.subscribers.DisposableSubscriber
  */
-public abstract class Flowable<@NonNull T> implements Publisher<T> {
+public abstract non-sealed class Flowable<@NonNull T> implements Publisher<T>,
+FlowableDocBasic<T>
+{
     /** The default buffer size. */
     static final int BUFFER_SIZE;
     static {
@@ -10146,29 +10149,12 @@ public final Single<T> elementAtOrError(long index) {
         return RxJavaPlugins.onAssembly(new FlowableElementAtSingle<>(this, index, null));
     }
 
-    /**
-     * Filters items emitted by the current {@code Flowable} by only emitting those that satisfy a specified predicate.
-     * <p>
-     * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/filter.v3.png" alt="">
-     * <dl>
-     *  <dt><b>Backpressure:</b></dt>
-     *  <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
-     *  behavior.</dd>
-     *  <dt><b>Scheduler:</b></dt>
-     *  <dd>{@code filter} does not operate by default on a particular {@link Scheduler}.</dd>
-     * </dl>
-     *
-     * @param predicate
-     *            a function that evaluates each item emitted by the current {@code Flowable}, returning {@code true}
-     *            if it passes the filter
-     * @return the new {@code Flowable} instance
-     * @throws NullPointerException if {@code predicate} is {@code null}
-     * @see <a href="http://reactivex.io/documentation/operators/filter.html">ReactiveX operators documentation: Filter</a>
-     */
+    /** {@inheritDoc} */
     @CheckReturnValue
     @NonNull
     @BackpressureSupport(BackpressureKind.PASS_THROUGH)
     @SchedulerSupport(SchedulerSupport.NONE)
+    @Override
     public final Flowable<T> filter(@NonNull Predicate<? super T> predicate) {
         Objects.requireNonNull(predicate, "predicate is null");
         return RxJavaPlugins.onAssembly(new FlowableFilter<>(this, predicate));
@@ -12038,31 +12024,12 @@ public final Single<T> lastOrError() {
         return RxJavaPlugins.onAssembly(new FlowableLift<>(this, lifter));
     }
 
-    /**
-     * Returns a {@code Flowable} that applies a specified function to each item emitted by the current {@code Flowable} and
-     * emits the results of these function applications.
-     * <p>
-     * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/map.v3.png" alt="">
-     * <dl>
-     *  <dt><b>Backpressure:</b></dt>
-     *  <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
-     *  behavior.</dd>
-     *  <dt><b>Scheduler:</b></dt>
-     *  <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
-     * </dl>
-     *
-     * @param <R> the output type
-     * @param mapper
-     *            a function to apply to each item emitted by the current {@code Flowable}
-     * @return the new {@code Flowable} instance
-     * @throws NullPointerException if {@code mapper} is {@code null}
-     * @see <a href="http://reactivex.io/documentation/operators/map.html">ReactiveX operators documentation: Map</a>
-     * @see #mapOptional(Function)
-     */
+    /** {@inheritDoc} */
     @CheckReturnValue
     @NonNull
     @BackpressureSupport(BackpressureKind.PASS_THROUGH)
     @SchedulerSupport(SchedulerSupport.NONE)
+    @Override
     public final <@NonNull R> Flowable<R> map(@NonNull Function<? super T, ? extends R> mapper) {
         Objects.requireNonNull(mapper, "mapper is null");
         return RxJavaPlugins.onAssembly(new FlowableMap<>(this, mapper));
diff --git a/src/main/java/io/reactivex/rxjava4/core/docs/FlowableDocBasic.java b/src/main/java/io/reactivex/rxjava4/core/docs/FlowableDocBasic.java
@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2016-present, RxJava Contributors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+ * compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is
+ * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
+ * the License for the specific language governing permissions and limitations under the License.
+ */
+package io.reactivex.rxjava4.core.docs;
+
+import io.reactivex.rxjava4.annotations.*;
+import io.reactivex.rxjava4.core.*;
+import io.reactivex.rxjava4.functions.*;
+
+/**
+ * Documents a set of operators so that the main Flowable source file is not cluttered.
+ * @param <T> the element type of the flow
+ */
+public sealed interface FlowableDocBasic<T> permits Flowable {
+    /**
+     * Returns a {@code Flowable} that applies a specified function to each item emitted by the current {@code Flowable} and
+     * emits the results of these function applications.
+     * <p>
+     * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/map.v3.png" alt="">
+     * <dl>
+     *  <dt><b>Backpressure:</b></dt>
+     *  <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
+     *  behavior.</dd>
+     *  <dt><b>Scheduler:</b></dt>
+     *  <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
+     * </dl>
+     *
+     * @param <R> the output type
+     * @param mapper
+     *            a function to apply to each item emitted by the current {@code Flowable}
+     * @return the new {@code Flowable} instance
+     * @throws NullPointerException if {@code mapper} is {@code null}
+     * @see <a href="http://reactivex.io/documentation/operators/map.html">ReactiveX operators documentation: Map</a>
+     * @see #mapOptional(Function)
+     */
+    @CheckReturnValue
+    @NonNull
+    @BackpressureSupport(BackpressureKind.PASS_THROUGH)
+    @SchedulerSupport(SchedulerSupport.NONE)
+    <@NonNull R> Flowable<R> map(@NonNull Function<? super T, ? extends R> mapper);
+
+    /**
+     * Filters items emitted by the current {@code Flowable} by only emitting those that satisfy a specified predicate.
+     * <p>
+     * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/filter.v3.png" alt="">
+     * <dl>
+     *  <dt><b>Backpressure:</b></dt>
+     *  <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
+     *  behavior.</dd>
+     *  <dt><b>Scheduler:</b></dt>
+     *  <dd>{@code filter} does not operate by default on a particular {@link Scheduler}.</dd>
+     * </dl>
+     *
+     * @param predicate
+     *            a function that evaluates each item emitted by the current {@code Flowable}, returning {@code true}
+     *            if it passes the filter
+     * @return the new {@code Flowable} instance
+     * @throws NullPointerException if {@code predicate} is {@code null}
+     * @see <a href="http://reactivex.io/documentation/operators/filter.html">ReactiveX operators documentation: Filter</a>
+     */
+    @CheckReturnValue
+    @NonNull
+    @BackpressureSupport(BackpressureKind.PASS_THROUGH)
+    @SchedulerSupport(SchedulerSupport.NONE)
+    Flowable<T> filter(@NonNull Predicate<? super T> predicate);
+
+}
diff --git a/src/test/java/io/reactivex/rxjava4/validators/BaseTypeParser.java b/src/test/java/io/reactivex/rxjava4/validators/BaseTypeParser.java
@@ -53,6 +53,9 @@ public static List<RxMethod> parse(File f, String baseClassName) throws Exceptio
         StringBuilder b = JavadocForAnnotations.readFile(f);
 
         int baseIndex = b.indexOf("public abstract class " + baseClassName);
+        if (baseIndex < 0) {
+            baseIndex = b.indexOf("public abstract non-sealed class " + baseClassName);
+        }
 
         if (baseIndex < 0) {
             throw new AssertionError("Wrong base class file: " + baseClassName);
diff --git a/src/test/java/io/reactivex/rxjava4/validators/JavadocForAnnotations.java b/src/test/java/io/reactivex/rxjava4/validators/JavadocForAnnotations.java
@@ -90,14 +90,17 @@ static final void scanFor(StringBuilder sourceCode, String annotation, String in
                 int k = sourceCode.indexOf(inDoc, j);
 
                 if (k < 0 || k > idx) {
-                    // when printed on the console, IDEs will create a clickable link to help navigate to the offending point
-                    e.append("java.lang.RuntimeException: missing ").append(inDoc).append(" section\r\n")
-                    ;
-                    int lc = lineNumber(sourceCode, idx);
-
-                    e.append(" at io.reactivex.rxjava4.core.").append(baseClassName)
-                    .append(" (").append(baseClassName).append(".java:")
-                    .append(lc).append(")").append("\r\n\r\n");
+                    var subSource = sourceCode.substring(j, idx);
+                    if (!subSource.startsWith("/** {@inheritDoc} */")) {
+                        // when printed on the console, IDEs will create a clickable link to help navigate to the offending point
+                        e.append("java.lang.RuntimeException: missing ").append(inDoc).append(" section\r\n")
+                        ;
+                        int lc = lineNumber(sourceCode, idx);
+
+                        e.append(" at io.reactivex.rxjava4.core.").append(baseClassName)
+                        .append(" (").append(baseClassName).append(".java:")
+                        .append(lc).append(")").append("\r\n\r\n");
+                    }
                 }
             }
 
diff --git a/src/test/java/io/reactivex/rxjava4/validators/JavadocWording.java b/src/test/java/io/reactivex/rxjava4/validators/JavadocWording.java
@@ -1107,8 +1107,15 @@ static void aOrAn(StringBuilder e, RxMethod m, String wrongPre, String word, Str
             }
             int nn = javadoc2.indexOf(" ", jj + 2);
             int mm = javadoc2.indexOf("}", jj + 2);
+            
+            if (nn > mm) {
+                nn = mm - 1;
+            }
 
-            javadoc2 = javadoc2.substring(0, jj) + javadoc2.substring(nn + 1, mm) + javadoc2.substring(mm + 1);
+            var jd2 = javadoc2;
+            javadoc2 = jd2.substring(0, jj);
+            javadoc2 += jd2.substring(nn + 1, mm);
+            javadoc2 += jd2.substring(mm + 1);
 
             kk = mm + 1;
         }
diff --git a/src/test/java/io/reactivex/rxjava4/validators/NoAnonymousInnerClassesTest.java b/src/test/java/io/reactivex/rxjava4/validators/NoAnonymousInnerClassesTest.java
@@ -23,7 +23,7 @@ public class NoAnonymousInnerClassesTest {
 
     @Test
     public void verify() throws Exception {
-        URL u = NoAnonymousInnerClassesTest.class.getResource("/");
+        URL u = NoAnonymousInnerClassesTest.class.getResource("");
         File f = new File(u.toURI());
 
         String fs = f.toString().toLowerCase().replace("\\", "/");
diff --git a/src/test/java/io/reactivex/rxjava4/validators/ParamValidationNaming.java b/src/test/java/io/reactivex/rxjava4/validators/ParamValidationNaming.java
@@ -249,6 +249,11 @@ static void processFile(Class<?> clazz) throws Exception {
                     boolean found = false;
                     for (int k = midx - 1; k >= 0; k--) {
                         String linek = lines.get(k).trim();
+                        if (linek.startsWith("/** {@inheritDoc} */")) {
+                            found = true;
+                            // the docs in in the sealed doc class, skip the check
+                            break;
+                        }
                         if (linek.startsWith("/**")) {
                             break;
                         }
@@ -366,6 +371,11 @@ static void processFile(Class<?> clazz) throws Exception {
                                 boolean found = false;
                                 for (int k = i - 1; k >= 0; k--) {
                                     String linek = lines.get(k).trim();
+                                    if (linek.startsWith("/** {@inheritDoc} */")) {
+                                        found = true;
+                                        break;
+                                        // the document is in the sealed doc interface
+                                    }
                                     if (linek.startsWith("/**")) {
                                         break;
                                     }
