Skip to content

Commit fc03afa

Browse files
zamullazamulla
authored
update: merging kotlinlang docs updated to the Writerside format
Related: JetBrains/kotlin-web-site#4458
2 parents d8d6f8f + 73fe783 commit fc03afa

19 files changed

+333
-320
lines changed

Diff for: ‎docs/cfg/buildprofiles.xml

+8-9
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
<?xml version="1.0" encoding="UTF-8"?>
2-
3-
<buildprofiles>
4-
<variables>
5-
<enable-browser-edits>true</enable-browser-edits>
6-
<browser-edits-url>https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/</browser-edits-url>
7-
<allow-indexable-eaps>true</allow-indexable-eaps>
8-
</variables>
9-
<build-profile product="kc"/>
10-
</buildprofiles>
2+
<buildprofiles xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd">
3+
<variables>
4+
<enable-browser-edits>true</enable-browser-edits>
5+
<browser-edits-url>https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/</browser-edits-url>
6+
<allow-indexable-eaps>true</allow-indexable-eaps>
7+
</variables>
8+
<build-profile instance="kc"/>
9+
</buildprofiles>

Diff for: ‎docs/kc.tree

+19-25
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,19 @@
1-
<?xml version="1.0" encoding="UTF-8"?>
2-
3-
<!DOCTYPE product-profile
4-
SYSTEM "https://resources.jetbrains.com/stardust/product-profile.dtd">
5-
6-
<product-profile id="kc"
7-
name="Kotlin coroutines"
8-
start-page="coroutines-guide.md">
9-
10-
<chunk include-id="coroutines">
11-
<toc-element id="coroutines-guide.md"/>
12-
<toc-element id="coroutines-basics.md" accepts-web-file-names="basics.html,coroutines-basic-jvm.html"/>
13-
<toc-element id="coroutines-and-channels.md"/>
14-
<toc-element id="cancellation-and-timeouts.md"/>
15-
<toc-element id="composing-suspending-functions.md"/>
16-
<toc-element id="coroutine-context-and-dispatchers.md"/>
17-
<toc-element id="flow.md"/>
18-
<toc-element id="channels.md"/>
19-
<toc-element id="exception-handling.md"/>
20-
<toc-element id="shared-mutable-state-and-concurrency.md"/>
21-
<toc-element id="select-expression.md"/>
22-
<toc-element id="debug-coroutines-with-idea.md"/>
23-
<toc-element id="debug-flow-with-idea.md"/>
24-
</chunk>
25-
</product-profile>
1+
<?xml version='1.0' encoding='utf-8'?>
2+
<!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
3+
<instance-profile id="kc" name="Kotlin coroutines" start-page="coroutines-guide.md">
4+
<snippet id="coroutines">
5+
<toc-element topic="coroutines-guide.md"/>
6+
<toc-element accepts-web-file-names="basics.html,coroutines-basic-jvm.html" topic="coroutines-basics.md"/>
7+
<toc-element topic="coroutines-and-channels.md"/>
8+
<toc-element topic="cancellation-and-timeouts.md"/>
9+
<toc-element topic="composing-suspending-functions.md"/>
10+
<toc-element topic="coroutine-context-and-dispatchers.md"/>
11+
<toc-element topic="flow.md"/>
12+
<toc-element topic="channels.md"/>
13+
<toc-element topic="exception-handling.md"/>
14+
<toc-element topic="shared-mutable-state-and-concurrency.md"/>
15+
<toc-element topic="select-expression.md"/>
16+
<toc-element topic="debug-coroutines-with-idea.md"/>
17+
<toc-element topic="debug-flow-with-idea.md"/>
18+
</snippet>
19+
</instance-profile>

Diff for: ‎docs/project.ihp

-14
This file was deleted.

Diff for: ‎docs/topics/cancellation-and-timeouts.md

+23-22
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
<!--- TEST_NAME CancellationGuideTest -->
2+
<contribute-url>https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/</contribute-url>
23

34
[//]: # (title: Cancellation and timeouts)
45

@@ -32,9 +33,9 @@ fun main() = runBlocking {
3233
```
3334
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
3435

35-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt).
36+
> 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).
3637
>
37-
{type="note"}
38+
{style="note"}
3839

3940
It produces the following output:
4041

@@ -86,9 +87,9 @@ fun main() = runBlocking {
8687
```
8788
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
8889

89-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt).
90+
> 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).
9091
>
91-
{type="note"}
92+
{style="note"}
9293

9394
Run it to see that it continues to print "I'm sleeping" even after cancellation
9495
until the job completes by itself after five iterations.
@@ -131,9 +132,9 @@ fun main() = runBlocking {
131132
```
132133
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
133134

134-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt).
135+
> 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).
135136
>
136-
{type="note"}
137+
{style="note"}
137138

138139
While catching `Exception` is an anti-pattern, this issue may surface in more subtle ways, like when using the
139140
[`runCatching`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/run-catching.html) function,
@@ -173,9 +174,9 @@ fun main() = runBlocking {
173174
```
174175
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
175176

176-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt).
177+
> 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).
177178
>
178-
{type="note"}
179+
{style="note"}
179180

180181
As you can see, now this loop is cancelled. [isActive] is an extension property
181182
available inside the coroutine via the [CoroutineScope] object.
@@ -188,7 +189,7 @@ main: I'm tired of waiting!
188189
main: Now I can quit.
189190
-->
190191

191-
## Closing resources with `finally`
192+
## Closing resources with finally
192193

193194
Cancellable suspending functions throw [CancellationException] on cancellation, which can be handled in
194195
the usual way. For example, the `try {...} finally {...}` expression and Kotlin's `use` function execute their
@@ -218,9 +219,9 @@ fun main() = runBlocking {
218219
```
219220
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
220221

221-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt).
222+
> 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).
222223
>
223-
{type="note"}
224+
{style="note"}
224225

225226
Both [join][Job.join] and [cancelAndJoin] wait for all finalization actions to complete,
226227
so the example above produces the following output:
@@ -273,9 +274,9 @@ fun main() = runBlocking {
273274
```
274275
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
275276

276-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-06.kt).
277+
> 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).
277278
>
278-
{type="note"}
279+
{style="note"}
279280

280281
<!--- TEST
281282
job: I'm sleeping 0 ...
@@ -311,9 +312,9 @@ fun main() = runBlocking {
311312
```
312313
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
313314

314-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-07.kt).
315+
> 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).
315316
>
316-
{type="note"}
317+
{style="note"}
317318

318319
It produces the following output:
319320

@@ -354,9 +355,9 @@ fun main() = runBlocking {
354355
```
355356
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
356357

357-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-08.kt).
358+
> 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).
358359
>
359-
{type="note"}
360+
{style="note"}
360361

361362
There is no longer an exception when running this code:
362363

@@ -415,9 +416,9 @@ fun main() {
415416
```
416417
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
417418

418-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-09.kt).
419+
> 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).
419420
>
420-
{type="note"}
421+
{style="note"}
421422

422423
<!--- CLEAR -->
423424

@@ -428,7 +429,7 @@ of your machine. You may need to tweak the timeout in this example to actually s
428429
> since it always happens from the same thread, the one used by `runBlocking`.
429430
> More on that will be explained in the chapter on coroutine context.
430431
>
431-
{type="note"}
432+
{style="note"}
432433

433434
To work around this problem you can store a reference to the resource in a variable instead of returning it
434435
from the `withTimeout` block.
@@ -468,9 +469,9 @@ fun main() {
468469
```
469470
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
470471

471-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-10.kt).
472+
> 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).
472473
>
473-
{type="note"}
474+
{style="note"}
474475

475476
This example always prints zero. Resources do not leak.
476477

Diff for: ‎docs/topics/channels.md

+23-22
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
<!--- TEST_NAME ChannelsGuideTest -->
2+
<contribute-url>https://github.com/Kotlin/kotlinx.coroutines/edit/master/docs/topics/</contribute-url>
23

34
[//]: # (title: Channels)
45

@@ -31,9 +32,9 @@ fun main() = runBlocking {
3132
```
3233
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
3334

34-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-01.kt).
35+
> 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).
3536
>
36-
{type="note"}
37+
{style="note"}
3738

3839
The output of this code is:
3940

@@ -77,9 +78,9 @@ fun main() = runBlocking {
7778
```
7879
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
7980

80-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-02.kt).
81+
> 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).
8182
>
82-
{type="note"}
83+
{style="note"}
8384

8485
<!--- TEST
8586
1
@@ -118,9 +119,9 @@ fun main() = runBlocking {
118119
```
119120
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
120121

121-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-03.kt).
122+
> 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).
122123
>
123-
{type="note"}
124+
{style="note"}
124125

125126
<!--- TEST
126127
1
@@ -182,9 +183,9 @@ fun CoroutineScope.square(numbers: ReceiveChannel<Int>): ReceiveChannel<Int> = p
182183
```
183184
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
184185

185-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-04.kt).
186+
> 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).
186187
>
187-
{type="note"}
188+
{style="note"}
188189

189190
<!--- TEST
190191
1
@@ -199,7 +200,7 @@ Done!
199200
> so that we can rely on [structured concurrency](composing-suspending-functions.md#structured-concurrency-with-async) to make
200201
> sure that we don't have lingering global coroutines in our application.
201202
>
202-
{type="note"}
203+
{style="note"}
203204

204205
## Prime numbers with pipeline
205206

@@ -225,7 +226,7 @@ fun CoroutineScope.filter(numbers: ReceiveChannel<Int>, prime: Int) = produce<In
225226
Now we build our pipeline by starting a stream of numbers from 2, taking a prime number from the current channel,
226227
and launching new pipeline stage for each prime number found:
227228

228-
```Plain Text
229+
```
229230
numbersFrom(2) -> filter(2) -> filter(3) -> filter(5) -> filter(7) ...
230231
```
231232

@@ -266,9 +267,9 @@ fun CoroutineScope.filter(numbers: ReceiveChannel<Int>, prime: Int) = produce<In
266267
```
267268
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
268269

269-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-05.kt).
270+
> 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).
270271
>
271-
{type="note"}
272+
{style="note"}
272273

273274
The output of this code is:
274275

@@ -360,9 +361,9 @@ fun CoroutineScope.launchProcessor(id: Int, channel: ReceiveChannel<Int>) = laun
360361
```
361362
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
362363

363-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-06.kt).
364+
> 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).
364365
>
365-
{type="note"}
366+
{style="note"}
366367

367368
The output will be similar to the following one, albeit the processor ids that receive
368369
each specific integer may be different:
@@ -435,9 +436,9 @@ suspend fun sendString(channel: SendChannel<String>, s: String, time: Long) {
435436
```
436437
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
437438

438-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-07.kt).
439+
> 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).
439440
>
440-
{type="note"}
441+
{style="note"}
441442

442443
The output is:
443444

@@ -485,9 +486,9 @@ fun main() = runBlocking<Unit> {
485486
```
486487
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
487488

488-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-08.kt).
489+
> 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).
489490
>
490-
{type="note"}
491+
{style="note"}
491492

492493
It prints "sending" _five_ times using a buffered channel with capacity of _four_:
493494

@@ -538,9 +539,9 @@ suspend fun player(name: String, table: Channel<Ball>) {
538539
```
539540
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
540541

541-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-09.kt).
542+
> 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).
542543
>
543-
{type="note"}
544+
{style="note"}
544545

545546
The "ping" coroutine is started first, so it is the first one to receive the ball. Even though "ping"
546547
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> {
602603
```
603604
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
604605

605-
> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-channel-10.kt).
606+
> 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).
606607
>
607-
{type="note"}
608+
{style="note"}
608609

609610
It prints following lines:
610611

0 commit comments

Comments
 (0)