2.x: ObservableEmitter/FlowableEmitter Javadoc Improvement

[hborders]

The javadoc for ObservableEmtter states:

The emitter allows the registration of a single resource, in the form of a Disposable or Cancellable via setDisposable(Disposable) or setCancellable(Cancellable) respectively. The emitter implementations will dispose/cancel this instance when the downstream cancels the flow or after the event generator logic calls Emitter.onError(Throwable), Emitter.onComplete() or when tryOnError(Throwable) succeeds.

Similarly, the javadoc for FlowableEmitter states:

The emitter allows the registration of a single resource, in the form of a Disposable or Cancellable via setDisposable(Disposable) or setCancellable(Cancellable) respectively. The emitter implementations will dispose/cancel this instance when the downstream cancels the flow or after the event generator logic calls Emitter.onError(Throwable), Emitter.onComplete() or when tryOnError(Throwable) succeeds.

when the downstream cancels the flow is ambiguous for a noobie like me. It isn't clear that a subscriber calling dispose will [cancel] the flow. It would be very helpful if the relationship between the *Emitter and the downstream subscriber was more explicit.

[akarnokd]

You mean replace "cancels" in ObservableEmitter with "disposes"?

[hborders]

I mean the documentation should explicitly say that dispose-ing a subscriber will dispose the Observable for which ObservableEmitter supplies events.

when the downstream cancels the flow is the confusing part, and I'm not sure where the documentation talks about this.

[hborders]

I was under the impression that in general, an Observable or Flowable was designed to have potentially many subscribers, and so it's counter-intuitive that disposing a single subscriber would thus dispose the Observable/Flowable.

[akarnokd]

I'm not sure if we want to put that level of documentation detail into those interfaces. There is a short example in the Observable JavaDocs that demonstrates disposing a sequence which is currently not there for Flowable.

I was under the impression that in general, an Observable or Flowable was designed to have potentially many subscribers, and so it's counter-intuitive that disposing a single subscriber would thus dispose the Observable/Flowable.

A subscriber/observer cancels/disposes the dedicated subscription object established when calling subscribe with said consumer. Yes, the terminology is somewhat imprecise and we use "cancels the Flowable" still as a shorthand for it.

[hborders]

A subscriber/observer cancels/disposes the dedicated subscription object

Does this mean that the ObservableEmitter is the dedicated subscription object?

[akarnokd]

Technically, yes.

[akarnokd]

If you want, you can create a PR with your proposed documentation changes.

[akarnokd]

Closing via #6535 for 3.x. If you want, you can backport it to 2.x.