@@ -82,7 +82,7 @@ import kotlin.jvm.*
8282 * which effectively requests a buffer of any size. Multiple requests with a specified buffer
8383 * size produce a buffer with the sum of the requested buffer sizes.
8484 *
85- * A `buffer` call with a non-default value of the [onBufferOverflow] parameter overrides all immediately preceding
85+ * A `buffer` call with a non-[SUSPEND] value of the [onBufferOverflow] parameter overrides all immediately preceding
8686 * buffering operators, because it never suspends its upstream, and thus no upstream buffer would ever be used.
8787 *
8888 * ### Conceptual implementation
@@ -106,8 +106,8 @@ import kotlin.jvm.*
106106 * ### Conflation
107107 *
108108 * Usage of this function with [capacity] of [Channel.CONFLATED][Channel.CONFLATED] is a shortcut to
109- * `buffer(onBufferOverflow = `[`BufferOverflow.DROP_OLDEST`][BufferOverflow.DROP_OLDEST]`)`, and is available via
110- * a separate [conflate] operator. See its documentation for details .
109+ * `buffer(capacity = 0, onBufferOverflow = `[`BufferOverflow.DROP_OLDEST`][BufferOverflow.DROP_OLDEST]`)`,
110+ * and is available via a separate [conflate] operator.
111111 *
112112 * @param capacity type/capacity of the buffer between coroutines. Allowed values are the same as in `Channel(...)`
113113 * factory function: [BUFFERED][Channel.BUFFERED] (by default), [CONFLATED][Channel.CONFLATED],
@@ -147,6 +147,9 @@ public fun <T> Flow<T>.buffer(capacity: Int = BUFFERED): Flow<T> = buffer(capaci
147147 * The effect of this is that emitter is never suspended due to a slow collector, but collector
148148 * always gets the most recent value emitted.
149149 *
150+ * This is a shortcut for `buffer(capacity = 0, onBufferOverflow = BufferOverflow.DROP_OLDEST)`.
151+ * See the [buffer] operator for other configuration options.
152+ *
150153 * For example, consider the flow that emits integers from 1 to 30 with 100 ms delay between them:
151154 *
152155 * ```
@@ -174,7 +177,11 @@ public fun <T> Flow<T>.buffer(capacity: Int = BUFFERED): Flow<T> = buffer(capaci
174177 *
175178 * Adjacent applications of `conflate`/[buffer], [channelFlow], [flowOn] and [produceIn] are
176179 * always fused so that only one properly configured channel is used for execution.
177- * **Conflation takes precedence over `buffer()` calls with any other capacity.**
180+ *
181+ * If there was no explicit buffer size specified, then the buffer size is `0`.
182+ * Otherwise, the buffer size is unchanged.
183+ * The strategy for buffer overflow becomes [BufferOverflow.DROP_OLDEST] after the application of this operator,
184+ * but can be overridden later.
178185 *
179186 * Note that any instance of [StateFlow] already behaves as if `conflate` operator is
180187 * applied to it, so applying `conflate` to a `StateFlow` has no effect.
0 commit comments