Update the Javadoc of the retry operator (#6458)

Specify that the `times` function parameter describes "the number of times
to resubscribe if the current *operator* fails".

Also, this commit updates some unit tests to illustrate the Javadoc wording.

Solves: #6402

Author: RomanWuattier

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

@@ -2090,7 +2090,7 @@ public final Completable retry(BiPredicate<? super Integer, ? super Throwable> p
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
-     * @param times the number of times the returned Completable should retry this Completable
+     * @param times the number of times to resubscribe if the current Completable fails
      * @return the new Completable instance
      * @throws IllegalArgumentException if times is negative
      */
@@ -2110,7 +2110,7 @@ public final Completable retry(long times) {
      *  <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
      * <p>History: 2.1.8 - experimental
-     * @param times the number of times the returned Completable should retry this Completable
+     * @param times the number of times to resubscribe if the current Completable fails
      * @param predicate the predicate that is called with the latest throwable and should return
      * true to indicate the returned Completable should resubscribe to this Completable.
      * @return the new Completable instance

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

@@ -13399,7 +13399,7 @@ public final Flowable<T> retry(BiPredicate<? super Integer, ? super Throwable> p
      * </dl>
      *
      * @param count
-     *            number of retry attempts before failing
+     *            the number of times to resubscribe if the current Flowable fails
      * @return the source Publisher modified with retry logic
      * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
      */
@@ -13420,7 +13420,7 @@ public final Flowable<T> retry(long count) {
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
-     * @param times the number of times to repeat
+     * @param times the number of times to resubscribe if the current Flowable fails
      * @param predicate the predicate called with the failure Throwable and should return true to trigger a retry.
      * @return the new Flowable instance
      */

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

@@ -4031,7 +4031,7 @@ public final Maybe<T> retry(BiPredicate<? super Integer, ? super Throwable> pred
      * </dl>
      *
      * @param count
-     *            number of retry attempts before failing
+     *            the number of times to resubscribe if the current Maybe fails
      * @return the new Maybe instance
      * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
      */
@@ -4048,7 +4048,7 @@ public final Maybe<T> retry(long count) {
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
-     * @param times the number of times to repeat
+     * @param times the number of times to resubscribe if the current Maybe fails
      * @param predicate the predicate called with the failure Throwable and should return true to trigger a retry.
      * @return the new Maybe instance
      */

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

@@ -11075,7 +11075,7 @@ public final Observable<T> retry(BiPredicate<? super Integer, ? super Throwable>
      * </dl>
      *
      * @param times
-     *            number of retry attempts before failing
+     *            the number of times to resubscribe if the current Observable fails
      * @return the source ObservableSource modified with retry logic
      * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
      */
@@ -11093,7 +11093,7 @@ public final Observable<T> retry(long times) {
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
-     * @param times the number of times to repeat
+     * @param times the number of times to resubscribe if the current Observable fails
      * @param predicate the predicate called with the failure Throwable and should return true to trigger a retry.
      * @return the new Observable instance
      */

src/test/java/io/reactivex/completable/CompletableTest.java

@@ -2398,18 +2398,20 @@ public void retryTimes5Error() {
 
     @Test(timeout = 5000)
     public void retryTimes5Normal() {
-        final AtomicInteger calls = new AtomicInteger(5);
+        final AtomicInteger calls = new AtomicInteger();
 
         Completable c = Completable.fromAction(new Action() {
             @Override
             public void run() {
-                if (calls.decrementAndGet() != 0) {
+                if (calls.incrementAndGet() != 6) {
                     throw new TestException();
                 }
             }
         }).retry(5);
 
         c.blockingAwait();
+
+        assertEquals(6, calls.get());
     }
 
     @Test(expected = IllegalArgumentException.class)

src/test/java/io/reactivex/internal/operators/single/SingleMiscTest.java

@@ -27,7 +27,9 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
 
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNotSame;
 import static org.junit.Assert.assertSame;
 
@@ -199,11 +201,13 @@ public boolean test(Integer i, Throwable e) throws Exception {
 
     @Test
     public void retryTimes() {
+        final AtomicInteger calls = new AtomicInteger();
+
         Single.fromCallable(new Callable<Object>() {
-            int c;
+
             @Override
             public Object call() throws Exception {
-                if (++c != 5) {
+                if (calls.incrementAndGet() != 6) {
                     throw new TestException();
                 }
                 return 1;
@@ -212,6 +216,8 @@ public Object call() throws Exception {
         .retry(5)
         .test()
         .assertResult(1);
+
+        assertEquals(6, calls.get());
     }
 
     @Test

src/test/java/io/reactivex/maybe/MaybeTest.java

@@ -3185,6 +3185,19 @@ public Publisher<Object> apply(Flowable<? extends Throwable> v) throws Exception
                 return (Publisher)v;
             }
         }).test().assertResult(1);
+
+        final AtomicInteger calls = new AtomicInteger();
+        try {
+            Maybe.error(new Callable<Throwable>() {
+                @Override
+                public Throwable call() {
+                    calls.incrementAndGet();
+                    return new TestException();
+                }
+            }).retry(5).test();
+        } finally {
+            assertEquals(6, calls.get());
+        }
     }
 
     @Test