MPP: Single documentation for kotlinx-coroutines-core with platform tags

elizarov · elizarov · commit 4cdf8836f44d · 2017-12-26T14:12:33.000+03:00
diff --git a/common/kotlinx-coroutines-core-common/README.md b/common/kotlinx-coroutines-core-common/README.md
@@ -3,42 +3,6 @@
 Common primitives to work with coroutines in
 [mutliplatform Kotlin projects](https://kotlinlang.org/docs/reference/multiplatform.html).
 
-Note, that documentation is currently provided in platform-specific modules only:
+Documentation is provided in platform-specific modules:
 * [kotlinx-coroutines-core](../../core/kotlinx-coroutines-core/README.md) for Kotlin/JVM.
 * [kotlinx-coroutines-core-js](../../js/kotlinx-coroutines-core-js/README.md) for Kotlin/JS.
-
-Coroutine builder functions:
-
-| **Name**      | **Result**    | **Scope**        | **Description**
-| ------------- | ------------- | ---------------- | ---------------
-| `launch`      | `Job`         | `CoroutineScope` | Launches coroutine that does not have any result 
-| `async`       | `Deferred`    | `CoroutineScope` | Returns a single value with the future result
-| `runBlocking` | `T`           | `CoroutineScope` | Blocks the event loop while the coroutine runs
-
-Coroutine dispatchers implementing `CoroutineDispatcher`:
- 
-| **Name**                    | **Description**
-| --------------------------- | ---------------
-| `DefaultDispatcher`         | Platform-specific default dispatcher
-| `Unconfined`                | Does not confine coroutine execution in any way
-
-More context elements:
-
-| **Name**                    | **Description**
-| --------------------------- | ---------------
-| `NonCancellable`            | A non-cancelable job that is always active
-| `CoroutineExceptionHandler` | Handler for uncaught exception
-
-Top-level suspending functions:
-
-| **Name**            | **Description**
-| ------------------- | ---------------
-| `delay`             | Non-blocking sleep
-| `yield`             | Yields thread in single-threaded dispatchers
-| `withContext`       | Switches to a different context
-| `withTimeout`       | Set execution time-limit with exception on timeout 
-| `withTimeoutOrNull` | Set execution time-limit will null result on timeout
-
-Cancellation support for user-defined suspending functions is available with `suspendCancellableCoroutine`
-helper function. `NonCancellable` job object is provided to suppress cancellation with 
-`run(NonCancellable) {...}` block of code.
diff --git a/gradle/dokka.gradle b/gradle/dokka.gradle
@@ -3,65 +3,75 @@
 def platform = platformOf(project)
 def coroutines_core = platformLib("kotlinx-coroutines-core", platform)
 
-if (platform != "common") {
-    apply plugin: 'org.jetbrains.dokka'
+def makeLinkMapping(dokka, projectDir) {
+    dokka.linkMapping {
+        def relPath = rootProject.projectDir.toPath().relativize(projectDir.toPath())
+        dir = "$projectDir/src/main/kotlin"
+        url = "http://github.com/kotlin/kotlinx.coroutines/tree/master/$relPath/src/main/kotlin"
+        suffix = "#L"
+    }
 }
 
 if (platform == "jvm") {
-    // real xxx-javadoc.jar for JVM
-    task dokkaJavadoc(type: dokka.getClass()) {
-        outputFormat = 'javadoc'
-        outputDirectory = "$buildDir/javadoc"
-    }
+    apply plugin: 'org.jetbrains.dokka'
 
-    task javadocJar(type: Jar, dependsOn: dokkaJavadoc) {
-        classifier = 'javadoc'
-        from "$buildDir/javadoc"
-    }
-} else {
-    // empty xxx-javadoc.jar
-    task javadocJar(type: Jar) {
-        classifier = 'javadoc'
-        from "$buildDir/javadoc" // would not exist
+    tasks.withType(dokka.getClass()) {
+        jdkVersion = 8
+        includes = ['README.md']
     }
-}
 
-if (platform != "common") {
     dokka {
         outputFormat = 'kotlin-website'
     }
 
-    tasks.withType(dokka.getClass()) {
-        jdkVersion = 8
-        includes = ['README.md']
-        linkMapping {
-            def relPath = rootProject.projectDir.toPath().relativize(projectDir.toPath())
-            dir = "$projectDir/src/main/kotlin"
-            url = "http://github.com/kotlin/kotlinx.coroutines/tree/master/$relPath/src/main/kotlin"
-            suffix = "#L"
-        }
-        kotlinTasks { [] }
-        if (project.name == coroutines_core) {
-            impliedPlatforms = [platform]
+    if (project.name == coroutines_core) {
+        // Configuration for MPP module
+        dokka {
+            kotlinTasks { [] }
+            suppressedModifiers = ['actual']
+            // map for JS & Common sources
+            makeLinkMapping(it, projectDir)
+            makeLinkMapping(it, rootProject.file('js/kotlinx-coroutines-core-js'))
+            makeLinkMapping(it, rootProject.file('common/kotlinx-coroutines-core-common'))
+            // source roots
+            impliedPlatforms = ['JVM', 'JS']
             sourceRoot {
-                path = project.file('src/main/kotlin')
-                platforms = [platform]
+                path = rootProject.file('core/kotlinx-coroutines-core/src/main/kotlin')
+                platforms = ['JVM']
             }
             sourceRoot {
-                path = rootProject.file('common/kotlinx-coroutines-core-common/src/main/kotlin')
+                path = rootProject.file('js/kotlinx-coroutines-core-js/src/main/kotlin')
+                platforms = ['JS']
             }
-        } else {
             sourceRoot {
-                path = project.file('src/main/kotlin')
+                path = rootProject.file('common/kotlinx-coroutines-core-common/src/main/kotlin')
             }
-        }
-        afterEvaluate {
-            classpath = project.configurations.compileClasspath.files
-            dependsOn(project.configurations.compileClasspath)
-            if (platform == "js") {
-                def jvmlib = project.dependencies.create("org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version")
-                classpath += project.configurations.detachedConfiguration(jvmlib).files
+            // depends on JS & Common, too
+            afterEvaluate {
+                dependsOn(tasks.getByPath(":kotlinx-coroutines-core-js:classes"))
+                dependsOn(tasks.getByPath(":kotlinx-coroutines-core-common:classes"))
+            }
+            afterEvaluate {
+                classpath = project.configurations.compileClasspath.files
+                dependsOn(project.configurations.compileClasspath)
             }
         }
     }
+
+    // real xxx-javadoc.jar for JVM
+    task dokkaJavadoc(type: dokka.getClass()) {
+        outputFormat = 'javadoc'
+        outputDirectory = "$buildDir/javadoc"
+    }
+
+    task javadocJar(type: Jar, dependsOn: dokkaJavadoc) {
+        classifier = 'javadoc'
+        from "$buildDir/javadoc"
+    }
+} else {
+    // empty xxx-javadoc.jar for JS and Common modules
+    task javadocJar(type: Jar) {
+        classifier = 'javadoc'
+        from "$buildDir/javadoc" // would not exist
+    }
 }
diff --git a/js/kotlinx-coroutines-core-js/README.md b/js/kotlinx-coroutines-core-js/README.md
@@ -42,23 +42,23 @@ helper function. [NonCancellable] job object is provided to suppress cancellatio
 
 General-purpose coroutine builders, contexts, and helper functions.
 
-<!--- MODULE kotlinx-coroutines-core-js -->
+<!--- MODULE kotlinx-coroutines-core -->
 <!--- INDEX kotlinx.coroutines.experimental -->
-[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/launch.html
-[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-job/index.html
-[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-coroutine-scope/index.html
-[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/async.html
-[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-deferred/index.html
-[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/run-blocking.html
-[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
-[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-default-dispatcher.html
-[Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-unconfined/index.html
-[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-non-cancellable/index.html
-[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/-coroutine-exception-handler/index.html
-[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/delay.html
-[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/yield.html
-[withContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/with-context.html
-[withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/with-timeout.html
-[withTimeoutOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/with-timeout-or-null.html
-[suspendCancellableCoroutine]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core-js/kotlinx.coroutines.experimental/suspend-cancellable-coroutine.html
+[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
+[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/index.html
+[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
+[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/async.html
+[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
+[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
+[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
+[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-default-dispatcher.html
+[Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-unconfined/index.html
+[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
+[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-exception-handler/index.html
+[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html
+[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/yield.html
+[withContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-context.html
+[withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-timeout.html
+[withTimeoutOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-timeout-or-null.html
+[suspendCancellableCoroutine]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/suspend-cancellable-coroutine.html
 <!--- END -->
diff --git a/site/docs/_includes/head.html b/site/docs/_includes/head.html
@@ -6,6 +6,8 @@
   <meta name="description" content="{{ page.excerpt | default: site.description | strip_html | normalize_whitespace | truncate: 160 | escape }}">
   <link rel="stylesheet" href="{{ "/assets/main.css" | relative_url }}">
   <link rel="canonical" href="{{ page.url | replace:'index.html','' | absolute_url }}">
+  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
+  <script src="{{ "/assets/js/api.js" | relative_url }}"></script>
   <script>
     (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
             (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
diff --git a/site/docs/_sass/_api.scss b/site/docs/_sass/_api.scss
@@ -205,3 +205,21 @@ code :target {
 .parameterName {
   font-weight: bold;
 }
+
+// MPP projects
+
+.tags {
+  display: flex;
+}
+
+.tags__tag {
+  color: white;
+  font-weight: bold;
+  text-transform: uppercase;
+  background: #a7a7a7;
+  padding: 0 7px;
+  font-size: 10px;
+  border-radius: 9px;
+  line-height: 18px;
+  margin-right: 5px;
+}
diff --git a/site/docs/assets/js/api.js b/site/docs/assets/js/api.js
@@ -0,0 +1,31 @@
+/*
+ * Copyright 2016-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+function addTag(rowElement, tag) {
+    var tags = $(rowElement).find('.tags');
+    if (tags.length == 0) {
+        tags = $('<div class="tags"></div>');
+        $(rowElement).find('td:first').append(tags);
+    }
+    tags.append('<div class="tags__tag">' + tag + '</div>')
+}
+
+$(document).ready(function () {
+    $('[data-platform]').each(function (ind, element) {
+        var platform = element.getAttribute('data-platform');
+        addTag(element, platform)
+    });
+});
