Add terrakok/FlowMarbles as stories to the Flow documentation

build.gradle.kts

@@ -90,6 +90,7 @@ allprojects {
          */
         google()
         mavenCentral()
+        maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
         addDevRepositoryIfEnabled(this, project)
     }
 }

buildSrc/src/main/kotlin/dokka-conventions.gradle.kts

@@ -7,13 +7,15 @@ plugins {
 }
 
 val knit_version: String by project
+val storytale_version: String by project
 private val projetsWithoutDokka = unpublished + "kotlinx-coroutines-bom" + jdk8ObsoleteModule
 private val coreModuleDocsUrl = "https://kotlinlang.org/api/kotlinx.coroutines/$coreModule/"
 private val coreModuleDocsPackageList = "$projectDir/kotlinx-coroutines-core/build/dokka/htmlPartial/package-list"
 
 configure(subprojects.filterNot { projetsWithoutDokka.contains(it.name) }) {
     apply(plugin = "org.jetbrains.dokka")
     configurePathsaver()
+    configureStorytale()
     condigureDokkaSetup()
     configureExternalLinks()
 }
@@ -37,6 +39,12 @@ private fun Project.configurePathsaver() {
     }
 }
 
+private fun Project.configureStorytale() {
+    dependencies {
+        dokkaPlugin("org.jetbrains.compose.storytale:storytale-dokka-plugin:$storytale_version")
+    }
+}
+
 // Configure Dokka setup
 private fun Project.condigureDokkaSetup() {
     tasks.withType(DokkaTaskPartial::class).configureEach {
@@ -91,9 +99,13 @@ private fun Project.configureExternalLinks() {
  * - Templates repository: https://github.com/JetBrains/kotlin-web-site/tree/master/dokka-templates
  */
 private fun Project.setupDokkaTemplatesDir(dokkaTask: AbstractDokkaTask) {
-    dokkaTask.pluginsMapConfiguration = mapOf(
-        "org.jetbrains.dokka.base.DokkaBase" to """{ "templatesDir" : "${
-            project.rootProject.projectDir.toString().replace('\\', '/')
-        }/dokka-templates" }"""
-    )
+    val rootDir = project.rootProject.projectDir.toString().replace('\\', '/')
+    //language=JSON
+    val dokkaBaseConfiguration = """
+    {
+      "customStyleSheets": ["$rootDir/dokka-templates/styles/storytale-styles.css"],
+      "templatesDir": "$rootDir/dokka-templates"
+    }
+    """
+    dokkaTask.pluginsMapConfiguration = mapOf("org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration)
 }

dokka-templates/styles/storytale-styles.css

@@ -0,0 +1,28 @@
+.storytale-embedded-container {
+    container-type: inline-size;
+}
+
+.storytale-embedded {
+    min-height: 450px;
+    border: 1px solid lightgray;
+    border-radius: 8px;
+    overflow: hidden;
+}
+
+@container (max-width: 800px) {
+    .storytale-embedded {
+        aspect-ratio: 1 / 1;
+    }
+}
+
+@container (max-width: 700px) {
+    .storytale-embedded {
+        aspect-ratio: 15 / 16;
+    }
+}
+
+@container (max-width: 500px) {
+    .storytale-embedded {
+        aspect-ratio: 3 / 4;
+    }
+}

gradle.properties

@@ -11,6 +11,7 @@ benchmarks_jmh_version=1.37
 junit_version=4.12
 junit5_version=5.7.0
 knit_version=0.5.0
+storytale_version=0.0.4-alpha01+dev18
 lincheck_version=2.18.1
 dokka_version=2.0.0
 byte_buddy_version=1.10.9

kotlinx-coroutines-core/common/src/flow/operators/Delay.kt

@@ -26,6 +26,8 @@ fun main() = runBlocking {
 */
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/Debounce
+ *
  * Returns a flow that mirrors the original flow, but filters out values
  * that are followed by the newer values within the given [timeout][timeoutMillis].
  * The latest value is always emitted.

kotlinx-coroutines-core/common/src/flow/operators/Distinct.kt

@@ -31,6 +31,8 @@ public fun <T> Flow<T>.distinctUntilChanged(areEquivalent: (old: T, new: T) -> B
     distinctUntilChangedBy(keySelector = defaultKeySelector, areEquivalent = areEquivalent as (Any?, Any?) -> Boolean)
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/DistinctUntilChanged
+ *
  * Returns flow where all subsequent repetitions of the same key are filtered out, where
  * key is extracted with [keySelector] function.
  *

kotlinx-coroutines-core/common/src/flow/operators/Emitters.kt

@@ -13,6 +13,8 @@ import kotlin.jvm.*
 //   user code to directly emit to the underlying FlowCollector.
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/Transform
+ *
  * Applies [transform] function to each value of the given flow.
  *
  * The receiver of the `transform` is [FlowCollector] and thus `transform` is a

kotlinx-coroutines-core/common/src/flow/operators/Limit.kt

@@ -11,6 +11,8 @@ import kotlinx.coroutines.flow.flow as safeFlow
 import kotlinx.coroutines.flow.internal.unsafeFlow as flow
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/Drop
+ *
  * Returns a flow that ignores first [count] elements.
  * Throws [IllegalArgumentException] if [count] is negative.
  */
@@ -25,6 +27,8 @@ public fun <T> Flow<T>.drop(count: Int): Flow<T> {
 }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/DropWhile
+ *
  * Returns a flow containing all elements except first elements that satisfy the given predicate.
  */
 public fun <T> Flow<T>.dropWhile(predicate: suspend (T) -> Boolean): Flow<T> = flow {
@@ -40,6 +44,8 @@ public fun <T> Flow<T>.dropWhile(predicate: suspend (T) -> Boolean): Flow<T> = f
 }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/Take
+ *
  * Returns a flow that contains first [count] elements.
  * When [count] elements are consumed, the original flow is cancelled.
  * Throws [IllegalArgumentException] if [count] is not positive.
@@ -73,6 +79,8 @@ private suspend fun <T> FlowCollector<T>.emitAbort(value: T, ownershipMarker: An
 }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/TakeWhile
+ *
  * Returns a flow that contains first elements satisfying the given [predicate].
  *
  * Note, that the resulting flow does not contain the element on which the [predicate] returned `false`.
@@ -91,6 +99,8 @@ public fun <T> Flow<T>.takeWhile(predicate: suspend (T) -> Boolean): Flow<T> = f
 }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/TransformWhile
+ *
  * Applies [transform] function to each value of the given flow while this
  * function returns `true`.
  *

kotlinx-coroutines-core/common/src/flow/operators/Merge.kt

@@ -30,6 +30,8 @@ public val DEFAULT_CONCURRENCY: Int = systemProp(
 )
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/FlatMapConcat
+ *
  * Transforms elements emitted by the original flow by applying [transform], that returns another flow,
  * and then concatenating and flattening these flows.
  *
@@ -43,6 +45,8 @@ public fun <T, R> Flow<T>.flatMapConcat(transform: suspend (value: T) -> Flow<R>
     map(transform).flattenConcat()
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/FlatMapMerge
+ *
  * Transforms elements emitted by the original flow by applying [transform], that returns another flow,
  * and then merging and flattening these flows.
  *
@@ -103,6 +107,8 @@ public fun <T> Iterable<Flow<T>>.merge(): Flow<T> {
 }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/Merge
+ *
  * Merges the given flows into a single flow without preserving an order of elements.
  * All flows are merged concurrently, without limit on the number of simultaneously collected flows.
  *
@@ -138,6 +144,8 @@ public fun <T> Flow<Flow<T>>.flattenMerge(concurrency: Int = DEFAULT_CONCURRENCY
 }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/TransformLatest
+ *
  * Returns a flow that produces element by [transform] function every time the original flow emits a value.
  * When the original flow emits a new value, the previous `transform` block is cancelled, thus the name `transformLatest`.
  *
@@ -163,6 +171,8 @@ public fun <T, R> Flow<T>.transformLatest(@BuilderInference transform: suspend F
     ChannelFlowTransformLatest(transform, this)
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/FlatMapLatest
+ *
  * Returns a flow that switches to a new flow produced by [transform] function every time the original flow emits a value.
  * When the original flow emits a new value, the previous flow produced by `transform` block is cancelled.
  *
@@ -189,6 +199,8 @@ public inline fun <T, R> Flow<T>.flatMapLatest(@BuilderInference crossinline tra
     transformLatest { emitAll(transform(it)) }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/MapLatest
+ *
  * Returns a flow that emits elements from the original flow transformed by [transform] function.
  * When the original flow emits a new value, computation of the [transform] block for previous value is cancelled.
  *

kotlinx-coroutines-core/common/src/flow/operators/Transform.kt

@@ -12,6 +12,8 @@ import kotlinx.coroutines.flow.internal.unsafeFlow as flow
 import kotlinx.coroutines.flow.unsafeTransform as transform
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/Filter
+ *
  * Returns a flow containing only values of the original flow that match the given [predicate].
  */
 public inline fun <T> Flow<T>.filter(crossinline predicate: suspend (T) -> Boolean): Flow<T> = transform { value ->
@@ -44,6 +46,8 @@ public fun <T: Any> Flow<T?>.filterNotNull(): Flow<T> = transform<T?, T> { value
 }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/Map
+ *
  * Returns a flow containing the results of applying the given [transform] function to each value of the original flow.
  */
 public inline fun <T, R> Flow<T>.map(crossinline transform: suspend (value: T) -> R): Flow<R> = transform { value ->
@@ -59,6 +63,8 @@ public inline fun <T, R: Any> Flow<T>.mapNotNull(crossinline transform: suspend
 }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/WithIndex
+ *
  * Returns a flow that wraps each element into [IndexedValue], containing value and its index (starting from zero).
  */
 public fun <T> Flow<T>.withIndex(): Flow<IndexedValue<T>> = flow {
@@ -108,6 +114,8 @@ public fun <T, R> Flow<T>.runningFold(initial: R, @BuilderInference operation: s
 }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/RunningReduce
+ *
  * Reduces the given flow with [operation], emitting every intermediate result, including initial value.
  * The first element is taken as initial value for operation accumulator.
  * This operator has a sibling with initial value -- [scan].

kotlinx-coroutines-core/common/src/flow/operators/Zip.kt

@@ -10,6 +10,8 @@ import kotlinx.coroutines.flow.flow as safeFlow
 import kotlinx.coroutines.flow.internal.unsafeFlow as flow
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/Combine
+ *
  * Returns a [Flow] whose values are generated with [transform] function by combining
  * the most recently emitted values by each flow.
  *
@@ -306,6 +308,8 @@ public inline fun <reified T, R> combineTransform(
 }
 
 /**
+ * @story https://jsmonk.github.io/FlowMarbles/?embedded=true#story/Zip
+ *
  * Zips values from the current flow (`this`) with [other] flow using provided [transform] function applied to each pair of values.
  * The resulting flow completes as soon as one of the flows completes and cancel is called on the remaining flow.
  *