clarify behaviour of groupBy in javadoc

[davidmoten]

As discussed in #3411, some clarification of the behaviour of groupBy looks necessary re its behaviour when the GroupedObservable terminates early (for example has .first() applied to it). See also #3581.

I also took the liberty of recommending ignoreElements instead of take(0) for the section in the javadoc that recommends how to ignore emissions because the take(0) approach would have more overhead (every emission from source would prompt the emission of a new GroupedObservable) than the ignoreElements approach.

Once this is accepted I'll look to submit a PR with groupByOnce (mentioned in #3411).

[davidmoten]

Corrected the documentation that said resubscription occurs when it is rather a new GroupedObservable is emittted for a group.

[akarnokd]

GroupedObservable allows only a single Subscriber during its lifetime and if this Subscriber unsubscribes before the main source terminates, the next emission by the main source having the same key will trigger a new GroupedObservable emission.

[davidmoten]

Thanks @akarnokd, that does add information. I'll use that.

[davidmoten]

I notice that GroupedObservable itself doesn't have a single Subscriber restriction but certainly the GroupedObservable emitted by groupBy does have this property. I'll rejig the wording to get this across.

[davidmoten]

Incorporated @akarnokd suggestion

[akarnokd]

👍

[zsxwing]

👍

I also took the liberty of recommending ignoreElements instead of take(0) for the section in the javadoc that recommends how to ignore emissions because the take(0) approach would have more overhead (every emission from source would prompt the emission of a new GroupedObservable) than the ignoreElements approach.

By the way, ignoreElements has a drawback: It keeps all group Observables in memory even some of them won't emit items.