1.x and 2.x Javadoc for Completable's retryWhen differs from Observable, Single and Docs

[aballano]

While trying to use the retryWhen operator of the Completable I had problems understanding the behaviour detailed in it´s javadoc:

Returns a Completable which given a Publisher and when this Completable emits an error, delivers that error through an Observable and the Publisher should return a value indicating a retry in response or a terminal event indicating a termination.

Which highly differs from the documentation of Observable, Single and the docs, where the need of calling the provided observable's onNext/onError/onCompleted is more detailed:

Returns an Observable that emits the same values as the source observable with the exception of an {@code onError}. An {@code onError} notification from the source will result in the emission of a {@link Throwable} item to the Observable provided as an argument to the {@code notificationHandler} function. If that Observable calls {@code onComplete} or {@code onError} then {@code retry} will call {@code onCompleted} or {@code onError} on the child subscription. Otherwise, this Observable will resubscribe to the source Observable.

I could prepare a PR for both 1.x and 2.x versions if needed.

[akarnokd]

Most people set up a flow inside the retryWhen so nobody calls onNext manually in there. However, the text should use a bit of a cleanup:

Returns a Completable which given a Publisher and when this Completable emits an error, delivers that error through a Flowable and the Publisher should signal a value indicating a retry in response or a terminal event indicating a termination.

[aballano]

Subtle but meaningful change! :)

@akarnokd Would you prefer to do the change yourself or should I?

[akarnokd]

You are welcome to change 2.x. Don't change 1.x.

[aballano]

@akarnokd Any specific reason why not to change 1.x? Just curious.

[akarnokd]

Don't want to mix in 2.x terminology.

Closing via #4810.