Document streaming/collecting behavior for Flux return values

Closes gh-32630

Author: bclozel

Diff for: framework-docs/modules/ROOT/pages/web/webflux-reactive-libraries.adoc

@@ -4,26 +4,17 @@
 `spring-webflux` depends on `reactor-core` and uses it internally to compose asynchronous
 logic and to provide Reactive Streams support. Generally, WebFlux APIs return `Flux` or
 `Mono` (since those are used internally) and leniently accept any Reactive Streams
-`Publisher` implementation as input. The use of `Flux` versus `Mono` is important, because
-it helps to express cardinality -- for example, whether a single or multiple asynchronous
-values are expected, and that can be essential for making decisions (for example, when
-encoding or decoding HTTP messages).
+`Publisher` implementation as input.
+When a `Publisher` is provided, it can be treated only as a stream with unknown semantics (0..N).
+If, however, the semantics are known, you should wrap it with `Flux` or `Mono.from(Publisher)` instead
+of passing the raw `Publisher`.
+The use of `Flux` versus `Mono` is important, because it helps to express cardinality --
+for example, whether a single or multiple asynchronous values are expected,
+and that can be essential for making decisions (for example, when encoding or decoding HTTP messages).
 
 For annotated controllers, WebFlux transparently adapts to the reactive library chosen by
 the application. This is done with the help of the
 {spring-framework-api}/core/ReactiveAdapterRegistry.html[`ReactiveAdapterRegistry`], which
 provides pluggable support for reactive library and other asynchronous types. The registry
 has built-in support for RxJava 3, Kotlin coroutines and SmallRye Mutiny, but you can
 register others, too.
-
-For functional APIs (such as <<webflux-fn>>, the `WebClient`, and others), the general rules
-for WebFlux APIs apply -- `Flux` and `Mono` as return values and a Reactive Streams
-`Publisher` as input. When a `Publisher`, whether custom or from another reactive library,
-is provided, it can be treated only as a stream with unknown semantics (0..N). If, however,
-the semantics are known, you can wrap it with `Flux` or `Mono.from(Publisher)` instead
-of passing the raw `Publisher`.
-
-For example, given a `Publisher` that is not a `Mono`, the Jackson JSON message writer
-expects multiple values. If the media type implies an infinite stream (for example,
-`application/json+stream`), values are written and flushed individually. Otherwise,
-values are buffered into a list and rendered as a JSON array.

Diff for: framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc

@@ -4,9 +4,20 @@
 [.small]#xref:web/webmvc/mvc-controller/ann-methods/return-types.adoc[See equivalent in the Servlet stack]#
 
 The following table shows the supported controller method return values. Note that reactive
-types from libraries such as Reactor, RxJava, xref:web-reactive.adoc#webflux-reactive-libraries[or other] are
+types from libraries such as Reactor, RxJava, xref:web/webflux-reactive-libraries.adoc[or other] are
 generally supported for all return values.
 
+For return types like `Flux`, when multiple values are expected, elements are streamed as they come
+and are not buffered. This is the default behavior, as keeping a potentially large amount of elements in memory
+is not efficient. If the media type implies an infinite stream (for example,
+`application/json+stream`), values are written and flushed individually. Otherwise,
+values are written individually and the flushing happens separately.
+
+NOTE: If an error happens while an element is encoded to JSON, the response might have been written to and committed already
+and it is impossible at that point to render a proper error response.
+In some cases, applications can choose to trade memory efficiency for better handling such errors by buffering elements and encoding them all at once.
+Controllers can then return a `Flux<List<B>>`; Reactor provides a dedicated operator for that, `Flux#collectList()`.
+
 [cols="1,2", options="header"]
 |===
 | Controller method return value | Description