update: merging kotlinlang docs updated to the Writerside format

Related: JetBrains/kotlin-web-site#4458
CLOVIS-AI · Sep 25, 2024 · fc03afa · fc03afa
2 parents d8d6f8f + 73fe783
commit fc03afa
Show file tree

Hide file tree

Showing 19 changed files with 333 additions and 320 deletions.
diff --git a/docs/cfg/buildprofiles.xml b/docs/cfg/buildprofiles.xml
@@ -1,10 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
-<buildprofiles>
-    <variables>
-        <enable-browser-edits>true</enable-browser-edits>
-        <browser-edits-url>https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/</browser-edits-url>
-        <allow-indexable-eaps>true</allow-indexable-eaps>
-    </variables>
-    <build-profile product="kc"/>
-</buildprofiles>
+<buildprofiles xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd">
+	<variables>
+		<enable-browser-edits>true</enable-browser-edits>
+		<browser-edits-url>https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/</browser-edits-url>
+		<allow-indexable-eaps>true</allow-indexable-eaps>
+	</variables>
+	<build-profile instance="kc"/>
+</buildprofiles>
diff --git a/docs/kc.tree b/docs/kc.tree
@@ -1,25 +1,19 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!DOCTYPE product-profile
-        SYSTEM "https://resources.jetbrains.com/stardust/product-profile.dtd">
-
-<product-profile id="kc"
-                 name="Kotlin coroutines"
-                 start-page="coroutines-guide.md">
-
-    <chunk include-id="coroutines">
-        <toc-element id="coroutines-guide.md"/>
-        <toc-element id="coroutines-basics.md" accepts-web-file-names="basics.html,coroutines-basic-jvm.html"/>
-        <toc-element id="coroutines-and-channels.md"/>
-        <toc-element id="cancellation-and-timeouts.md"/>
-        <toc-element id="composing-suspending-functions.md"/>
-        <toc-element id="coroutine-context-and-dispatchers.md"/>
-        <toc-element id="flow.md"/>
-        <toc-element id="channels.md"/>
-        <toc-element id="exception-handling.md"/>
-        <toc-element id="shared-mutable-state-and-concurrency.md"/>
-        <toc-element id="select-expression.md"/>
-        <toc-element id="debug-coroutines-with-idea.md"/>
-        <toc-element id="debug-flow-with-idea.md"/>
-    </chunk>
-</product-profile>
+<?xml version='1.0' encoding='utf-8'?>
+<!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+<instance-profile id="kc" name="Kotlin coroutines" start-page="coroutines-guide.md">
+	<snippet id="coroutines">
+		<toc-element topic="coroutines-guide.md"/>
+		<toc-element accepts-web-file-names="basics.html,coroutines-basic-jvm.html" topic="coroutines-basics.md"/>
+		<toc-element topic="coroutines-and-channels.md"/>
+		<toc-element topic="cancellation-and-timeouts.md"/>
+		<toc-element topic="composing-suspending-functions.md"/>
+		<toc-element topic="coroutine-context-and-dispatchers.md"/>
+		<toc-element topic="flow.md"/>
+		<toc-element topic="channels.md"/>
+		<toc-element topic="exception-handling.md"/>
+		<toc-element topic="shared-mutable-state-and-concurrency.md"/>
+		<toc-element topic="select-expression.md"/>
+		<toc-element topic="debug-coroutines-with-idea.md"/>
+		<toc-element topic="debug-flow-with-idea.md"/>
+	</snippet>
+</instance-profile>
diff --git a/docs/project.ihp b/docs/project.ihp
diff --git a/docs/topics/cancellation-and-timeouts.md b/docs/topics/cancellation-and-timeouts.md
@@ -1,4 +1,5 @@
 <!--- TEST_NAME CancellationGuideTest -->
+<contribute-url>https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/</contribute-url>
 
 [//]: # (title: Cancellation and timeouts)
 
@@ -32,9 +33,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt).
 >
-{type="note"}
+{style="note"}
 
 It produces the following output:
 
@@ -86,9 +87,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt).
 >
-{type="note"}
+{style="note"}
 
 Run it to see that it continues to print "I'm sleeping" even after cancellation
 until the job completes by itself after five iterations.
@@ -131,9 +132,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt).
 >
-{type="note"}
+{style="note"}
 
 While catching `Exception` is an anti-pattern, this issue may surface in more subtle ways, like when using the
 [`runCatching`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/run-catching.html) function,
@@ -173,9 +174,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt).
 >
-{type="note"}
+{style="note"}
 
 As you can see, now this loop is cancelled. [isActive] is an extension property 
 available inside the coroutine via the [CoroutineScope] object.
@@ -188,7 +189,7 @@ main: I'm tired of waiting!
 main: Now I can quit.
 -->
 
-## Closing resources with `finally`
+## Closing resources with finally
 
 Cancellable suspending functions throw [CancellationException] on cancellation, which can be handled in 
 the usual way. For example, the `try {...} finally {...}` expression and Kotlin's `use` function execute their
@@ -218,9 +219,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt).
 >
-{type="note"}
+{style="note"}
 
 Both [join][Job.join] and [cancelAndJoin] wait for all finalization actions to complete, 
 so the example above produces the following output:
@@ -273,9 +274,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-06.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-06.kt).
 >
-{type="note"}
+{style="note"}
 
 <!--- TEST
 job: I'm sleeping 0 ...
@@ -311,9 +312,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-07.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-07.kt).
 >
-{type="note"}
+{style="note"}
 
 It produces the following output:
 
@@ -354,9 +355,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-08.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-08.kt).
 >
-{type="note"}
+{style="note"}
 
 There is no longer an exception when running this code:
 
@@ -415,9 +416,9 @@ fun main() {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-09.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-09.kt).
 >
-{type="note"}
+{style="note"}
 
 <!--- CLEAR -->
 
@@ -428,7 +429,7 @@ of your machine. You may need to tweak the timeout in this example to actually s
 > since it always happens from the same thread, the one used by `runBlocking`.
 > More on that will be explained in the chapter on coroutine context.
 > 
-{type="note"}
+{style="note"}
 
 To work around this problem you can store a reference to the resource in a variable instead of returning it 
 from the `withTimeout` block. 
@@ -468,9 +469,9 @@ fun main() {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-10.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-cancel-10.kt).
 >
-{type="note"}
+{style="note"}
 
 This example always prints zero. Resources do not leak.
 

diff --git a/docs/topics/channels.md b/docs/topics/channels.md
@@ -1,4 +1,5 @@
 <!--- TEST_NAME ChannelsGuideTest -->
+<contribute-url>https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/</contribute-url>
 
 [//]: # (title: Channels)
 
@@ -31,9 +32,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-01.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-01.kt).
 >
-{type="note"}
+{style="note"}
 
 The output of this code is:
 
@@ -77,9 +78,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-02.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-02.kt).
 >
-{type="note"}
+{style="note"}
 
 <!--- TEST 
 1
@@ -118,9 +119,9 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-03.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-03.kt).
 >
-{type="note"}
+{style="note"}
 
 <!--- TEST 
 1
@@ -182,9 +183,9 @@ fun CoroutineScope.square(numbers: ReceiveChannel<Int>): ReceiveChannel<Int> = p
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-04.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-04.kt).
 >
-{type="note"}
+{style="note"}
 
 <!--- TEST 
 1
@@ -199,7 +200,7 @@ Done!
 > so that we can rely on [structured concurrency](composing-suspending-functions.md#structured-concurrency-with-async) to make
 > sure that we don't have lingering global coroutines in our application.
 >
-{type="note"}
+{style="note"}
 
 ## Prime numbers with pipeline
 
@@ -225,7 +226,7 @@ fun CoroutineScope.filter(numbers: ReceiveChannel<Int>, prime: Int) = produce<In
 Now we build our pipeline by starting a stream of numbers from 2, taking a prime number from the current channel, 
 and launching new pipeline stage for each prime number found:
 
-```Plain Text
+```
 numbersFrom(2) -> filter(2) -> filter(3) -> filter(5) -> filter(7) ... 
 ```
 
@@ -266,9 +267,9 @@ fun CoroutineScope.filter(numbers: ReceiveChannel<Int>, prime: Int) = produce<In
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-05.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-05.kt).
 >
-{type="note"}
+{style="note"}
 
 The output of this code is:
 
@@ -360,9 +361,9 @@ fun CoroutineScope.launchProcessor(id: Int, channel: ReceiveChannel<Int>) = laun
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-06.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-06.kt).
 >
-{type="note"}
+{style="note"}
 
 The output will be similar to the following one, albeit the processor ids that receive
 each specific integer may be different:
@@ -435,9 +436,9 @@ suspend fun sendString(channel: SendChannel<String>, s: String, time: Long) {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-07.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-07.kt).
 >
-{type="note"}
+{style="note"}
 
 The output is:
 
@@ -485,9 +486,9 @@ fun main() = runBlocking<Unit> {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-08.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-08.kt).
 >
-{type="note"}
+{style="note"}
 
 It prints "sending" _five_ times using a buffered channel with capacity of _four_:
 
@@ -538,9 +539,9 @@ suspend fun player(name: String, table: Channel<Ball>) {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-09.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-09.kt).
 >
-{type="note"}
+{style="note"}
 
 The "ping" coroutine is started first, so it is the first one to receive the ball. Even though "ping"
 coroutine immediately starts receiving the ball again after sending it back to the table, the ball gets
@@ -602,9 +603,9 @@ fun main() = runBlocking<Unit> {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-10.kt).
+> You can get the full code [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/jvm/test/guide/example-channel-10.kt).
 >
-{type="note"}
+{style="note"}
 
 It prints following lines: