Skip to content

Commit 4cdf883

Browse files
elizarovelizarov
committed
MPP: Single documentation for kotlinx-coroutines-core with platform tags
1 parent 1097bc8 commit 4cdf883

File tree

6 files changed

+122
-97
lines changed

6 files changed

+122
-97
lines changed

‎common/kotlinx-coroutines-core-common/README.md‎

Lines changed: 1 addition & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -3,42 +3,6 @@
33
Common primitives to work with coroutines in
44
[mutliplatform Kotlin projects](https://kotlinlang.org/docs/reference/multiplatform.html).
55

6-
Note, that documentation is currently provided in platform-specific modules only:
6+
Documentation is provided in platform-specific modules:
77
* [kotlinx-coroutines-core](../../core/kotlinx-coroutines-core/README.md) for Kotlin/JVM.
88
* [kotlinx-coroutines-core-js](../../js/kotlinx-coroutines-core-js/README.md) for Kotlin/JS.
9-
10-
Coroutine builder functions:
11-
12-
| **Name** | **Result** | **Scope** | **Description**
13-
| ------------- | ------------- | ---------------- | ---------------
14-
| `launch` | `Job` | `CoroutineScope` | Launches coroutine that does not have any result
15-
| `async` | `Deferred` | `CoroutineScope` | Returns a single value with the future result
16-
| `runBlocking` | `T` | `CoroutineScope` | Blocks the event loop while the coroutine runs
17-
18-
Coroutine dispatchers implementing `CoroutineDispatcher`:
19-
20-
| **Name** | **Description**
21-
| --------------------------- | ---------------
22-
| `DefaultDispatcher` | Platform-specific default dispatcher
23-
| `Unconfined` | Does not confine coroutine execution in any way
24-
25-
More context elements:
26-
27-
| **Name** | **Description**
28-
| --------------------------- | ---------------
29-
| `NonCancellable` | A non-cancelable job that is always active
30-
| `CoroutineExceptionHandler` | Handler for uncaught exception
31-
32-
Top-level suspending functions:
33-
34-
| **Name** | **Description**
35-
| ------------------- | ---------------
36-
| `delay` | Non-blocking sleep
37-
| `yield` | Yields thread in single-threaded dispatchers
38-
| `withContext` | Switches to a different context
39-
| `withTimeout` | Set execution time-limit with exception on timeout
40-
| `withTimeoutOrNull` | Set execution time-limit will null result on timeout
41-
42-
Cancellation support for user-defined suspending functions is available with `suspendCancellableCoroutine`
43-
helper function. `NonCancellable` job object is provided to suppress cancellation with
44-
`run(NonCancellable) {...}` block of code.

‎gradle/dokka.gradle‎

Lines changed: 52 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -3,65 +3,75 @@
33
def platform = platformOf(project)
44
def coroutines_core = platformLib("kotlinx-coroutines-core", platform)
55

6-
if (platform != "common") {
7-
apply plugin: 'org.jetbrains.dokka'
6+
def makeLinkMapping(dokka, projectDir) {
7+
dokka.linkMapping {
8+
def relPath = rootProject.projectDir.toPath().relativize(projectDir.toPath())
9+
dir = "$projectDir/src/main/kotlin"
10+
url = "http://github.com/kotlin/kotlinx.coroutines/tree/master/$relPath/src/main/kotlin"
11+
suffix = "#L"
12+
}
813
}
914

1015
if (platform == "jvm") {
11-
// real xxx-javadoc.jar for JVM
12-
task dokkaJavadoc(type: dokka.getClass()) {
13-
outputFormat = 'javadoc'
14-
outputDirectory = "$buildDir/javadoc"
15-
}
16+
apply plugin: 'org.jetbrains.dokka'
1617

17-
task javadocJar(type: Jar, dependsOn: dokkaJavadoc) {
18-
classifier = 'javadoc'
19-
from "$buildDir/javadoc"
20-
}
21-
} else {
22-
// empty xxx-javadoc.jar
23-
task javadocJar(type: Jar) {
24-
classifier = 'javadoc'
25-
from "$buildDir/javadoc" // would not exist
18+
tasks.withType(dokka.getClass()) {
19+
jdkVersion = 8
20+
includes = ['README.md']
2621
}
27-
}
2822

29-
if (platform != "common") {
3023
dokka {
3124
outputFormat = 'kotlin-website'
3225
}
3326

34-
tasks.withType(dokka.getClass()) {
35-
jdkVersion = 8
36-
includes = ['README.md']
37-
linkMapping {
38-
def relPath = rootProject.projectDir.toPath().relativize(projectDir.toPath())
39-
dir = "$projectDir/src/main/kotlin"
40-
url = "http://github.com/kotlin/kotlinx.coroutines/tree/master/$relPath/src/main/kotlin"
41-
suffix = "#L"
42-
}
43-
kotlinTasks { [] }
44-
if (project.name == coroutines_core) {
45-
impliedPlatforms = [platform]
27+
if (project.name == coroutines_core) {
28+
// Configuration for MPP module
29+
dokka {
30+
kotlinTasks { [] }
31+
suppressedModifiers = ['actual']
32+
// map for JS & Common sources
33+
makeLinkMapping(it, projectDir)
34+
makeLinkMapping(it, rootProject.file('js/kotlinx-coroutines-core-js'))
35+
makeLinkMapping(it, rootProject.file('common/kotlinx-coroutines-core-common'))
36+
// source roots
37+
impliedPlatforms = ['JVM', 'JS']
4638
sourceRoot {
47-
path = project.file('src/main/kotlin')
48-
platforms = [platform]
39+
path = rootProject.file('core/kotlinx-coroutines-core/src/main/kotlin')
40+
platforms = ['JVM']
4941
}
5042
sourceRoot {
51-
path = rootProject.file('common/kotlinx-coroutines-core-common/src/main/kotlin')
43+
path = rootProject.file('js/kotlinx-coroutines-core-js/src/main/kotlin')
44+
platforms = ['JS']
5245
}
53-
} else {
5446
sourceRoot {
55-
path = project.file('src/main/kotlin')
47+
path = rootProject.file('common/kotlinx-coroutines-core-common/src/main/kotlin')
5648
}
57-
}
58-
afterEvaluate {
59-
classpath = project.configurations.compileClasspath.files
60-
dependsOn(project.configurations.compileClasspath)
61-
if (platform == "js") {
62-
def jvmlib = project.dependencies.create("org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version")
63-
classpath += project.configurations.detachedConfiguration(jvmlib).files
49+
// depends on JS & Common, too
50+
afterEvaluate {
51+
dependsOn(tasks.getByPath(":kotlinx-coroutines-core-js:classes"))
52+
dependsOn(tasks.getByPath(":kotlinx-coroutines-core-common:classes"))
53+
}
54+
afterEvaluate {
55+
classpath = project.configurations.compileClasspath.files
56+
dependsOn(project.configurations.compileClasspath)
6457
}
6558
}
6659
}
60+
61+
// real xxx-javadoc.jar for JVM
62+
task dokkaJavadoc(type: dokka.getClass()) {
63+
outputFormat = 'javadoc'
64+
outputDirectory = "$buildDir/javadoc"
65+
}
66+
67+
task javadocJar(type: Jar, dependsOn: dokkaJavadoc) {
68+
classifier = 'javadoc'
69+
from "$buildDir/javadoc"
70+
}
71+
} else {
72+
// empty xxx-javadoc.jar for JS and Common modules
73+
task javadocJar(type: Jar) {
74+
classifier = 'javadoc'
75+
from "$buildDir/javadoc" // would not exist
76+
}
6777
}

‎js/kotlinx-coroutines-core-js/README.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -42,23 +42,23 @@ helper function. [NonCancellable] job object is provided to suppress cancellatio
4242

4343
General-purpose coroutine builders, contexts, and helper functions.
4444

45-
<!--- MODULE kotlinx-coroutines-core-js -->
45+
<!--- MODULE kotlinx-coroutines-core -->
4646
<!--- INDEX kotlinx.coroutines.experimental -->
47-
[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/launch.html
48-
[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-job/index.html
49-
[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-coroutine-scope/index.html
50-
[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/async.html
51-
[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-deferred/index.html
52-
[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/run-blocking.html
53-
[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
54-
[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-default-dispatcher.html
55-
[Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-unconfined/index.html
56-
[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-non-cancellable/index.html
57-
[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-coroutine-exception-handler/index.html
58-
[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/delay.html
59-
[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/yield.html
60-
[withContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/with-context.html
61-
[withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/with-timeout.html
62-
[withTimeoutOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/with-timeout-or-null.html
63-
[suspendCancellableCoroutine]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/suspend-cancellable-coroutine.html
47+
[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
48+
[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/index.html
49+
[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
50+
[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/async.html
51+
[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
52+
[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
53+
[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
54+
[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-default-dispatcher.html
55+
[Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-unconfined/index.html
56+
[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
57+
[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-exception-handler/index.html
58+
[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html
59+
[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/yield.html
60+
[withContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-context.html
61+
[withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-timeout.html
62+
[withTimeoutOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-timeout-or-null.html
63+
[suspendCancellableCoroutine]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/suspend-cancellable-coroutine.html
6464
<!--- END -->

‎site/docs/_includes/head.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
<meta name="description" content="{{ page.excerpt | default: site.description | strip_html | normalize_whitespace | truncate: 160 | escape }}">
77
<link rel="stylesheet" href="{{ "/assets/main.css" | relative_url }}">
88
<link rel="canonical" href="{{ page.url | replace:'index.html','' | absolute_url }}">
9+
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
10+
<script src="{{ "/assets/js/api.js" | relative_url }}"></script>
911
<script>
1012
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
1113
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),

‎site/docs/_sass/_api.scss‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,3 +205,21 @@ code :target {
205205
.parameterName {
206206
font-weight: bold;
207207
}
208+
209+
// MPP projects
210+
211+
.tags {
212+
display: flex;
213+
}
214+
215+
.tags__tag {
216+
color: white;
217+
font-weight: bold;
218+
text-transform: uppercase;
219+
background: #a7a7a7;
220+
padding: 0 7px;
221+
font-size: 10px;
222+
border-radius: 9px;
223+
line-height: 18px;
224+
margin-right: 5px;
225+
}

‎site/docs/assets/js/api.js‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
/*
2+
* Copyright 2016-2017 JetBrains s.r.o.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
function addTag(rowElement, tag) {
18+
var tags = $(rowElement).find('.tags');
19+
if (tags.length == 0) {
20+
tags = $('<div class="tags"></div>');
21+
$(rowElement).find('td:first').append(tags);
22+
}
23+
tags.append('<div class="tags__tag">' + tag + '</div>')
24+
}
25+
26+
$(document).ready(function () {
27+
$('[data-platform]').each(function (ind, element) {
28+
var platform = element.getAttribute('data-platform');
29+
addTag(element, platform)
30+
});
31+
});

0 commit comments

Comments
 (0)