[doc] Document usage of Mono.zip() along with Mono<Void> (#3306)

[RomaKudryavtsev]

Documented that upon supply of Mono it is not guaranteed that the resulted zipped Mono will not complete immediately upon empty completion of Mono. Fixes #3306
Author: Roman Zandler rmnzndlr@gmail.com

[chemicL]

I'm a bit skeptical of the use of the combinator in the examples, and especially the return of Void value in the Function. I have a feeling the explanation can be simpler. I believe it's also my mistake to assume we're documenting behaviour in case of Void, but narrowing it down to this specific case makes the comprehension more difficult. The principle applies to any type.

Consider the following alternative, without using Void:

@Test
public void testZipEmptyCompletionAllSubscribed() {
	AtomicInteger cnt = new AtomicInteger();
	Mono<Integer> mono1 = Mono.create(sink -> {
		cnt.incrementAndGet();
		sink.success();
	});
	Mono<Integer> mono2 = Mono.create(sink -> {
		cnt.incrementAndGet();
		sink.success();
	});
	Mono<Integer> zippedMono = Mono.zip(mono1, mono2, (v1, v2) -> v1);
	zippedMono.subscribe();
	assertEquals(2, cnt.get());
}

@Test
public void testZipEmptyCompletionOneSubscribed() {
	AtomicInteger cnt = new AtomicInteger();
	Mono<Integer> mono1 = Mono.create(sink -> {
		cnt.incrementAndGet();
		sink.success();
	});
	Mono<Integer> mono2 = Mono.create(sink -> {
		cnt.incrementAndGet();
		sink.success();
	});
	Mono<Integer> mono3 = Mono.create(sink -> {
		cnt.incrementAndGet();
		sink.success();
	});
	Mono<Integer> zippedMono = Mono.zip(mono1, Mono.zip(mono2, mono3, (v1, v2) -> v1), (v1, v2) -> v1);
	zippedMono.subscribe();
	assertEquals(1, cnt.get());
}

@Test
public void testZipOptionalAllSubscribed() {
	AtomicInteger cnt = new AtomicInteger();
	Mono<Integer> mono1 = Mono.create(sink -> {
		cnt.incrementAndGet();
		sink.success();
	});
	Mono<Integer> mono2 = Mono.create(sink -> {
		cnt.incrementAndGet();
		sink.success();
	});
	Mono<Integer> mono3 = Mono.create(sink -> {
		cnt.incrementAndGet();
		sink.success();
	});
	Mono<Optional<Integer>> zippedMono =
			Mono.zip(
					mono1.singleOptional(),
					Mono.zip(mono2.singleOptional(), mono3.singleOptional(), (v1, v2) -> v1),
					(v1, v2) -> v1);
	zippedMono.subscribe();
	assertEquals(3, cnt.get());
}

[RomaKudryavtsev]

@chemicL , many thanks for your feedback! So, in fact, the problem lies not in the use of Void, but in the empty completion itself (and such behavior is pretty same with any type - e.g., Mono Integer as well). I will refactor then my input this weekend.

[RomaKudryavtsev]

@chemicL , I have committed changes in accordance with your above suggestions. Please let me know if anything else might be improved.

[chemicL]

Suggested change

	While in this case the resulting `zippedMono` does not complete immediately upon empty completion of `mono1`, such behaviour is not guaranteed for all cases. For instance, consider the following test case:
	While in this case the resulting `zippedMono` subscribes to both `mono1` and `mono2`, such behaviour is not guaranteed for all cases. For instance, consider the following test case:

[chemicL]

I think the language mentioning completing immediately is not the essence here and can be confusing. Whether it completes before or after is an implementation detail, but the user is most probably interested in the act of subscribing and processing the sources.

[chemicL]

Suggested change

	In this case upon empty completion of `mono1`, `zippedMono` completes immediately.
	In this case upon empty completion of `mono1`, `zippedMono` completes immediately and does not subscribe to `mono2` and `mono3`.

[chemicL]

Please consider rewriting this according to the above suggestions around subscription and not completion.

[chemicL]

I made some more comments. Thanks for revisiting once more. I think the essence here is - completion of one source without emitting an item can influence the act of subscribing to other sources in undefined ways. It can either subscribe and cancel / discard / never subscribe. As far as I understood the risk is not subscribing to most users and the goal here is to show how to ensure subscription to all the sources.

[RomaKudryavtsev]

@chemicL , many thanks for your feedback! I will revert with revisions in the following 2 days.

[RomaKudryavtsev]

@chemicL , hi! I have made some changes in accordance with your suggestions. Hopefully, now the description is clear enough.