2.x: improve JavaDocs of the subscribeActual methods (#5981)

Author: akarnokd

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

@@ -1927,8 +1927,11 @@ public final void subscribe(CompletableObserver s) {
     }
 
     /**
-     * Implement this to handle the incoming CompletableObserver and
+     * Implement this method to handle the incoming {@link CompletableObserver}s and
      * perform the business logic in your operator.
+     * <p>There is no need to call any of the plugin hooks on the current {@code Completable} instance or
+     * the {@code CompletableObserver}; all hooks and basic safeguards have been
+     * applied by {@link #subscribe(CompletableObserver)} before this method gets called.
      * @param s the CompletableObserver instance, never null
      */
     protected abstract void subscribeActual(CompletableObserver s);

src/main/java/io/reactivex/Flowable.java

@@ -14333,9 +14333,10 @@ public final void subscribe(FlowableSubscriber<? super T> s) {
 
     /**
      * Operator implementations (both source and intermediate) should implement this method that
-     * performs the necessary business logic.
-     * <p>There is no need to call any of the plugin hooks on the current Flowable instance or
-     * the Subscriber.
+     * performs the necessary business logic and handles the incoming {@link Subscriber}s.
+     * <p>There is no need to call any of the plugin hooks on the current {@code Flowable} instance or
+     * the {@code Subscriber}; all hooks and basic safeguards have been
+     * applied by {@link #subscribe(Subscriber)} before this method gets called.
      * @param s the incoming Subscriber, never null
      */
     protected abstract void subscribeActual(Subscriber<? super T> s);

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

@@ -4082,7 +4082,10 @@ public final void subscribe(MaybeObserver<? super T> observer) {
     }
 
     /**
-     * Override this method in subclasses to handle the incoming MaybeObservers.
+     * Implement this method in subclasses to handle the incoming {@link MaybeObserver}s.
+     * <p>There is no need to call any of the plugin hooks on the current {@code Maybe} instance or
+     * the {@code MaybeObserver}; all hooks and basic safeguards have been
+     * applied by {@link #subscribe(MaybeObserver)} before this method gets called.
      * @param observer the MaybeObserver to handle, not null
      */
     protected abstract void subscribeActual(MaybeObserver<? super T> observer);

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

@@ -12039,9 +12039,10 @@ public final void subscribe(Observer<? super T> observer) {
 
     /**
      * Operator implementations (both source and intermediate) should implement this method that
-     * performs the necessary business logic.
-     * <p>There is no need to call any of the plugin hooks on the current Observable instance or
-     * the Subscriber.
+     * performs the necessary business logic and handles the incoming {@link Observer}s.
+     * <p>There is no need to call any of the plugin hooks on the current {@code Observable} instance or
+     * the {@code Observer}; all hooks and basic safeguards have been
+     * applied by {@link #subscribe(Observer)} before this method gets called.
      * @param observer the incoming Observer, never null
      */
     protected abstract void subscribeActual(Observer<? super T> observer);

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

@@ -3304,7 +3304,10 @@ public final void subscribe(SingleObserver<? super T> subscriber) {
     }
 
     /**
-     * Override this method in subclasses to handle the incoming SingleObservers.
+     * Implement this method in subclasses to handle the incoming {@link SingleObserver}s.
+     * <p>There is no need to call any of the plugin hooks on the current {@code Single} instance or
+     * the {@code SingleObserver}; all hooks and basic safeguards have been
+     * applied by {@link #subscribe(SingleObserver)} before this method gets called.
      * @param observer the SingleObserver to handle, not null
      */
     protected abstract void subscribeActual(@NonNull SingleObserver<? super T> observer);