Naming/Javadoc suggestions for Retry.java

Documentation Issue

I think that both the naming and the javadoc regarding number of retries in Retry.java could use some changes for clarity.

• Naming. totalRetries is great, but totalRetriesInARow is, IMHO, if not confusing then not greatly named. My suggestion is to deprecate it and change to consecutiveRetries.
• I think the javadoc part ZERO BASED... should be omitted. The gist of can also be read as... is perfectly sufficient, keep it simple and the word retries (“re” being the key) cannot mean anything else. Also, a 0-index for the error... is potentially misleading given the error - I first read it as a count of errors with a specific kind of Throwable, as if there were parallell counts (one per Throwable-type or something like that) going on.

Improvement Suggestion

My suggestions for the javadoc of those methods:

Returns: the total number of retries since the source first was subscribed to.

and

Returns: the number of retries since the latest onNext(), or since the source first was subscribed to if there hasn't been any onNext() signals (in which case totalRetries() and consecutiveRetries() are equivalent).

Also I suggest that both the parts that might result in a retry attempt and that potentially triggers a retry (in generateCompanion() and RetrySignal) be removed. I understand them, but I think it can be misleading, it might be interpreted as if the signals themselves would trigger retries given state x or y. It should be clear that the signal-flux is just a provider of signals/metadata and that it’s up to the companion to react to it and decide if there should be any retries or not (even if one decides to return the flux itself, but that’s probably not the most common use-case).

Happy to submit a PR if you like any of it.

[simonbasle]

All good, easy enough 😄

[simonbasle]

hi @mickeelm. At the time I tried to come up with a meaningful name, always a hard endeavor… the name has to stay for at least a while though, now that it has been (recently) released and part of the public API. we can definitely rework the javadoc and a PR with your suggestions would be very welcome there.

Keep in mind RetrySignal was added in 3.3.x so use that branch as the basis for your PR.