Merge "[kairos] Fix KDoc code snippet rendering" into main

     * observation of new emissions. It will however *not* cancel any running effects from previous

     * emissions. To achieve this behavior, use [launchScope] or [asyncScope] to create a child

     * build scope:

     * ``` kotlin

     * ```

     *   val job = launchScope {

     *       events.observe { x ->

     *           launchEffect { longRunningEffect(x) }

     *

     * By default, [builder] is only running while the returned [Events] is being

     * [observed][observe]. If you want it to run at all times, simply add a no-op observer:

     * ``` kotlin

     * ```

     *   events { ... }.apply { observe() }

     * ```

     */

     *

     * By default, [builder] is only running while the returned [Events] is being

     * [observed][observe]. If you want it to run at all times, simply add a no-op observer:

     * ``` kotlin

     * ```

     *   events { ... }.apply { observe() }

     * ```

     *

     * outside of the current Kairos transaction; when [transform] returns, the returned value is

     * emitted from the result [Events] in a new transaction.

     *

     * ``` kotlin

     * ```

     *     fun <A, B> Events<A>.mapAsyncLatest(transform: suspend (A) -> B): Events<B> =

     *         mapLatestBuild { a -> asyncEvent { transform(a) } }.flatten()

     * ```

    /**

     * Shorthand for:

     * ``` kotlin

     * ```

     * flow.toEvents().holdState(initialValue)

     * ```

     */

    /**

     * Shorthand for:

     * ``` kotlin

     * ```

     * flow.scan(initialValue, operation).toEvents().holdState(initialValue)

     * ```

     */

    /**

     * Shorthand for:

     * ``` kotlin

     * ```

     * flow.scan(initialValue) { a, f -> f(a) }.toEvents().holdState(initialValue)

     * ```

     */

     * be used to make further modifications to the Kairos network, and/or perform side-effects via

     * [effect].

     *

     * ``` kotlin

     * ```

     *     fun <A> State<A>.observeBuild(block: BuildScope.(A) -> Unit = {}): Job = launchScope {

     *         block(sample())

     *         changes.observeBuild(block)

 * outside of the current Kairos transaction; when it completes, the returned [Events] emits in a

 * new transaction.

 *

 * ``` kotlin

 * ```

 *   fun <A> BuildScope.asyncEvent(block: suspend () -> A): Events<A> =

 *       events { emit(block()) }.apply { observe() }

 * ```

 * executed if this [BuildScope] is still active by that time. It can be deactivated due to a

 * -Latest combinator, for example.

 *

 * ``` kotlin

 * ```

 *   fun BuildScope.effect(

 *       context: CoroutineContext = EmptyCoroutineContext,

 *       block: EffectScope.() -> Unit,

 * done because the current [BuildScope] might be deactivated within this transaction, perhaps due

 * to a -Latest combinator. If this happens, then the coroutine will never actually be started.

 *

 * ``` kotlin

 * ```

 *   fun BuildScope.launchEffect(block: suspend KairosScope.() -> Unit): Job =

 *       effect { effectCoroutineScope.launch { block() } }

 * ```

 * to a -Latest combinator. If this happens, then the coroutine will never actually be started.

 *

 * Shorthand for:

 * ``` kotlin

 * ```

 *   fun <R> BuildScope.asyncEffect(block: suspend KairosScope.() -> R): Deferred<R> =

 *       CompletableDeferred<R>.apply {

 *               effect { effectCoroutineScope.launch { complete(block()) } }

 *

 * By default, [builder] is only running while the returned [Events] is being

 * [observed][BuildScope.observe]. If you want it to run at all times, simply add a no-op observer:

 * ``` kotlin

 * ```

 * events { ... }.apply { observe() }

 * ```

 *

 *

 * By default, [builder] is only running while the returned [Events] is being

 * [observed][BuildScope.observe]. If you want it to run at all times, simply add a no-op observer:

 * ``` kotlin

 * ```

 * events { ... }.apply { observe() }

 * ```

 *

 *

 * Useful for recursive definitions.

 *

 * ``` kotlin

 * ```

 *   fun <A> Lazy<Events<A>>.defer() = deferredEvents { value }

 * ```

 *

 *

 * Useful for recursive definitions.

 *

 * ``` kotlin

 * ```

 *   fun <A> DeferredValue<Events<A>>.defer() = deferredEvents { get() }

 * ```

 *

 * Returns an [Events] that contains only the non-null results of applying [transform] to each value

 * of the original [Events].

 *

 * ``` kotlin

 * ```

 *  fun <A> Events<A>.mapNotNull(transform: TransactionScope.(A) -> B?): Events<B> =

 *      mapMaybe { if (it == null) absent else present(it) }

 * ```

 * Returns an [Events] that invokes [action] before each value of the original [Events] is emitted.

 * Useful for logging and debugging.

 *

 * ``` kotlin

 * ```

 *   fun <A> Events<A>.onEach(action: TransactionScope.(A) -> Unit): Events<A> =

 *       map { it.also { action(it) } }

 * ```

 * Splits an [Events] of pairs into a pair of [Events], where each returned [Events] emits half of

 * the original.

 *

 * ``` kotlin

 * ```

 *   fun <A, B> Events<Pair<A, B>>.unzip(): Pair<Events<A>, Events<B>> {

 *       val lefts = map { it.first }

 *       val rights = map { it.second }

/**

 * Returns an [Events] containing only values of the original [Events] that are not null.

 *

 * ``` kotlin

 * ```

 *  fun <A> Events<A?>.filterNotNull(): Events<A> = mapNotNull { it }

 * ```

 *

/**

 * Returns an [Events] containing only values of the original [Events] that are instances of [A].

 *

 * ``` kotlin

 * ```

 *   inline fun <reified A> Events<*>.filterIsInstance(): Events<A> =

 *       mapNotNull { it as? A }

 * ```

/**

 * Returns an [Events] containing only values of the original [Events] that are present.

 *

 * ``` kotlin

 * ```

 *  fun <A> Events<Maybe<A>>.filterPresent(): Events<A> = mapMaybe { it }

 * ```

 *

 * Returns an [Events] containing only values of the original [Events] that satisfy the given

 * [predicate].

 *

 * ``` kotlin

 * ```

 *   fun <A> Events<A>.filter(predicate: TransactionScope.(A) -> Boolean): Events<A> =

 *       mapMaybe { if (predicate(it)) present(it) else absent }

 * ```

 * downstream [Events]. The downstream [Events] are associated with a [key][K], which is derived

 * from each emission of the original [Events] via [extractKey].

 *

 * ``` kotlin

 * ```

 *   fun <K, A> Events<A>.groupBy(

 *       numKeys: Int? = null,

 *       extractKey: TransactionScope.(A) -> K,

 * Using this is equivalent to `upstream.filter(predicate) to upstream.filter { !predicate(it) }`

 * but is more efficient; specifically, [partition] will only invoke [predicate] once per element.

 *

 * ``` kotlin

 * ```

 *   fun <A> Events<A>.partition(

 *       predicate: TransactionScope.(A) -> Boolean

 *   ): Pair<Events<A>, Events<A>> =

 * [First]s and once for [Second]s, but is slightly more efficient; specifically, the

 * [filterIsInstance] check is only performed once per element.

 *

 * ``` kotlin

 * ```

 *   fun <A, B> Events<Either<A, B>>.partitionEither(): Pair<Events<A>, Events<B>> =

 *     map { it.asThese() }.partitionThese()

 * ```

 *

 * Useful for recursive definitions.

 *

 * ``` kotlin

 * ```

 *   fun <A> Lazy<Incremental<K, V>>.defer() = deferredIncremental { value }

 * ```

 */

 *

 * Useful for recursive definitions.

 *

 * ``` kotlin

 * ```

 *   fun <A> DeferredValue<Incremental<K, V>>.defer() = deferredIncremental { get() }

 * ```

 */