Android UI context implementation and Guide to UI programming with coroutines

Author: elizarov

README.md

@@ -2,23 +2,33 @@
 
 Library support for Kotlin coroutines. This is a companion version for Kotlin 1.1.0 release. 
 
-## Modules and features
-
-* [kotlinx-coroutines-core](kotlinx-coroutines-core) module with core primitives to work with coroutines. 
-  * This module's functionality is covered by the [guide to kotlinx.coroutines](coroutines-guide.md). 
-* [kotlinx-coroutines-jdk8](kotlinx-coroutines-jdk8) module with additional libraries for JDK8 (or Android API level 24).
-* [kotlinx-coroutines-nio](kotlinx-coroutines-nio) module with extensions for asynchronous IO on JDK7+.
-* [kotlinx-coroutines-swing](kotlinx-coroutines-swing) module with `Swing` context for Swing UI applications.
-* [kotlinx-coroutines-javafx](kotlinx-coroutines-javafx) module with `JavaFx` context for JavaFX UI applications.
-* [kotlinx-coroutines-reactive](kotlinx-coroutines-reactive) module with utilities for [Reactive Streams](http://www.reactive-streams.org)
-* [kotlinx-coroutines-rx1](kotlinx-coroutines-rx1) module with utilities for [RxJava 1.x](https://github.com/ReactiveX/RxJava/tree/1.x)
-* [kotlinx-coroutines-rx2](kotlinx-coroutines-rx2) module with utilities for [RxJava 2.x](https://github.com/ReactiveX/RxJava)
+## Modules
+
+Basic modules:
+
+* [kotlinx-coroutines-core](kotlinx-coroutines-core) -- core primitives to work with coroutines. 
+* [kotlinx-coroutines-jdk8](kotlinx-coroutines-jdk8) -- additional libraries for JDK8 (or Android API level 24).
+* [kotlinx-coroutines-nio](kotlinx-coroutines-nio) -- extensions for asynchronous IO on JDK7+.
+
+Modules that provide builders and iteration support for various reactive streams libraries:
+
+* [kotlinx-coroutines-reactive](kotlinx-coroutines-reactive) -- utilities for [Reactive Streams](http://www.reactive-streams.org)
+* [kotlinx-coroutines-rx1](kotlinx-coroutines-rx1) -- utilities for [RxJava 1.x](https://github.com/ReactiveX/RxJava/tree/1.x)
+* [kotlinx-coroutines-rx2](kotlinx-coroutines-rx2) -- utilities for [RxJava 2.x](https://github.com/ReactiveX/RxJava)
+
+Modules that provide coroutine dispatchers for various single-threaded UI libraries:
+
+* [kotlinx-coroutines-android](ui/kotlinx-coroutines-android) -- `UI` context for Android applications.
+* [kotlinx-coroutines-javafx](ui/kotlinx-coroutines-javafx) -- `JavaFx` context for JavaFX UI applications.
+* [kotlinx-coroutines-swing](ui/kotlinx-coroutines-swing) -- `Swing` context for Swing UI applications.
 
-## References and documentation
+## Documentation
 
-* [Guide to kotlinx.coroutines by example](coroutines-guide.md) 
+* [Guide to kotlinx.coroutines by example](coroutines-guide.md) (**read it first**)
+* [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md)
 * [Change log for kotlinx.coroutines](CHANGES.md)
 * [Coroutines design document (KEEP)](https://github.com/Kotlin/kotlin-coroutines/blob/master/kotlin-coroutines-informal.md)
+* [Full kotlinx.coroutines API reference](http://kotlin.github.io/kotlinx.coroutines)
 
 ## Using in your projects
 

knit/src/Knit.kt

@@ -67,7 +67,7 @@ fun knit(markdownFileName: String) {
     val test = arrayListOf<String>()
     var testOut: PrintWriter? = null
     var lastPgk: String? = null
-    val files = mutableSetOf<String>()
+    val files = mutableSetOf<File>()
     val allApiRefs = arrayListOf<ApiRef>()
     val remainingApiRefNames = mutableSetOf<String>()
     var siteRoot: String? = null
@@ -190,8 +190,9 @@ fun knit(markdownFileName: String) {
             }
             knitRegex?.find(inLine)?.let { knitMatch ->
                 val fileName = knitMatch.groups[1]!!.value
-                require(files.add(fileName)) { "Duplicate file name: $fileName"}
-                println("Knitting $fileName ...")
+                val file = File(markdownFile.parentFile, fileName)
+                require(files.add(file)) { "Duplicate file: $file"}
+                println("Knitting $file ...")
                 val outLines = arrayListOf<String>()
                 for (include in includes) {
                     val includeMatch = include.regex.matchEntire(fileName) ?: continue
@@ -204,7 +205,6 @@ fun knit(markdownFileName: String) {
                 }
                 outLines += code
                 code.clear()
-                val file = File(fileName)
                 val oldLines = try { file.readLines() } catch (e: IOException) { emptyList<String>() }
                 if (outLines != oldLines) writeLines(file, outLines)
             }
@@ -401,7 +401,6 @@ fun loadApiIndex(
     namePrefix: String = ""
 ): Map<String, String> {
     val fileName = docsRoot + "/" + path + INDEX_MD
-    println("Reading index from $fileName")
     val visited = mutableSetOf<String>()
     val map = HashMap<String,String>()
     File(fileName).withLineNumberReader<LineNumberReader>(::LineNumberReader) {
@@ -431,7 +430,12 @@ fun processApiIndex(
     remainingApiRefNames: MutableSet<String>
 ): List<String> {
     val key = ApiIndexKey(docsRoot, pkg)
-    val map = apiIndexCache.getOrPut(key, { loadApiIndex(docsRoot, pkg, pkg) })
+    val map = apiIndexCache.getOrPut(key, {
+        print("Parsing API docs at $docsRoot: ")
+        val result = loadApiIndex(docsRoot, pkg, pkg)
+        println("${result.size} definitions")
+        result
+    })
     val indexList = arrayListOf<String>()
     val it = remainingApiRefNames.iterator()
     while (it.hasNext()) {

pom.xml

@@ -97,14 +97,15 @@
 
     <modules>
         <module>kotlinx-coroutines-core</module>
-        <module>kotlinx-coroutines-swing</module>
-        <module>kotlinx-coroutines-javafx</module>
         <module>kotlinx-coroutines-jdk8</module>
         <module>kotlinx-coroutines-nio</module>
         <module>kotlinx-coroutines-reactive</module>
         <module>kotlinx-coroutines-rx1</module>
         <module>kotlinx-coroutines-rx2</module>
         <module>kotlinx-coroutines-rx-example</module>
+        <module>ui/kotlinx-coroutines-swing</module>
+        <module>ui/kotlinx-coroutines-javafx</module>
+        <module>ui/kotlinx-coroutines-android</module>
         <module>site</module>
     </modules>
 

site/build.xml

@@ -21,11 +21,12 @@
             <fileset dir="../kotlinx-coroutines-core/target/dokka" includes="**/*.md"/>
             <fileset dir="../kotlinx-coroutines-jdk8/target/dokka" includes="**/*.md"/>
             <fileset dir="../kotlinx-coroutines-nio/target/dokka" includes="**/*.md"/>
-            <fileset dir="../kotlinx-coroutines-swing/target/dokka" includes="**/*.md"/>
-            <fileset dir="../kotlinx-coroutines-javafx/target/dokka" includes="**/*.md"/>
             <fileset dir="../kotlinx-coroutines-reactive/target/dokka" includes="**/*.md"/>
             <fileset dir="../kotlinx-coroutines-rx1/target/dokka" includes="**/*.md"/>
             <fileset dir="../kotlinx-coroutines-rx2/target/dokka" includes="**/*.md"/>
+            <fileset dir="../ui/kotlinx-coroutines-android/target/dokka" includes="**/*.md"/>
+            <fileset dir="../ui/kotlinx-coroutines-javafx/target/dokka" includes="**/*.md"/>
+            <fileset dir="../ui/kotlinx-coroutines-swing/target/dokka" includes="**/*.md"/>
         </copy>
         <antcall target="jekyll"/>
     </target>

ui/README.md

@@ -0,0 +1,9 @@
+# Coroutines for UI
+
+This directory contains modules for coroutine programming with various single-threaded UI libraries:
+
+## Modules
+
+* [kotlinx-coroutines-android](kotlinx-coroutines-android) -- `UI` context for Android applications.
+* [kotlinx-coroutines-javafx](kotlinx-coroutines-javafx) -- `JavaFx` context for JavaFX UI applications.
+* [kotlinx-coroutines-swing](kotlinx-coroutines-swing) -- `Swing` context for Swing UI applications.