Add some comments for JS and multiplatform stuff

Author: jan-auer

build.gradle

@@ -11,6 +11,9 @@ buildscript {
 	}
 
 	dependencies {
+		// NOTE: Unfortunately we need to add these build dependencies in the
+		// top-level gradle file and not in :frontend, otherwise the build breaks.
+		// This will likely be resolved once the plugins become more stable.
 		classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 		classpath "org.jetbrains.kotlin:kotlin-frontend-plugin:0.0.21"
 	}

domain/src/main/kotlin/domain/Todo.kt

@@ -1,5 +1,16 @@
 package domain
 
+/**
+ * Shared domain object for Todos.
+ *
+ * Note that we're allowed to use all basic data types as well as types
+ * defined in kotlin-stdlib-common. We could also implement behavior here,
+ * as long as we don't rely on platform-specific code.
+ *
+ * For platform-specific behavior, we would have to create "header"
+ * declarations and "impl" them for all targets in their respective
+ * sub-projects. See https://vimeo.com/215556547#t=868s for more information.
+ */
 data class Todo(
         val id: String,
         val title: String,

frontend/build.gradle

@@ -1,8 +1,16 @@
 group 'org.example'
 version '1.0-SNAPSHOT'
 
+// NOTE: The plugins below have been declared in the top-level gradle file.
+// For some reason, declaring them here breaks the build. It is likely that
+// this issue will be resolved once the plugins become more stable.
+
+// Compile (i.e. transpile) kotlin to JS
+// We cannot use kotlin2js, as we need some new functionality
 apply plugin: 'kotlin-platform-js'
+// Add npm, webpack and karma support
 apply plugin: 'org.jetbrains.kotlin.frontend'
+// Add dead code elimination for kotlin.js
 apply plugin: 'kotlin-dce-js'
 
 repositories {
@@ -21,8 +29,15 @@ compileKotlin2Js {
 
 dependencies {
     compile "org.jetbrains.kotlin:kotlin-stdlib-js:$kotlin_version"
+
+    // Since we render HTML directly, we use kotlinx-html-js. There is also
+    // a server-side implementation to render static HTML. For highly dynamic
+    // though it makes more sense to use a framework like React or CycleJS.
     compile "org.jetbrains.kotlinx:kotlinx-html-js:0.6.4"
 
+    // Note "implement" instead of "compile" for dependencies to
+    // platform-common projects. This is only provided by kotlin-platform-
+    // common, but not by kotlin2js!
     implement project(":domain")
 }
 
@@ -33,16 +48,25 @@ kotlin {
 }
 
 kotlinFrontend {
+    // Generate a package.json and install dependencies during build
     npm {
         dependency "lodash"
     }
 
+    // Basic webpack configuration. More config goes in webpack.config.d
     webpackBundle {
         bundleName = "main"
     }
 
+    // This is where you switch on minification. Regardless, kotlin-dce
+    // will always run.
     define "PRODUCTION", false
 }
 
-// Run DCE on kotlin.js before building the final bundle
+// Run DCE on kotlin.js before building the final bundle. Sadly, this
+// dependency is not set automatically by kotlin-dce-js, so we have to
+// add it. If we leave this out, the minified kotlin.js is generated
+// too late and we end up with:
+//  - failing builds from a clean state
+//  - an outdated min/kotlin.js in incremental builds
 bundle.dependsOn runDceKotlinJs

frontend/src/main/kotlin/actions.kt

@@ -2,6 +2,9 @@ import domain.Todo
 import org.w3c.fetch.RequestInit
 import kotlin.browser.window
 
+/**
+ * Creates or updates a [todo] on the server and redraws the UI on success
+ */
 private fun putTodo(todo: Todo) {
     launch {
         window.fetch("http://localhost:8080/todo/${todo.id}", object : RequestInit {
@@ -13,12 +16,24 @@ private fun putTodo(todo: Todo) {
     }
 }
 
+/**
+ * Creates a new todo with the given [title]
+ *
+ * This method is asynchronous and automatically redraws the UI on completion. In case of an error,
+ * the error is printed to the console and the UI is not updated.
+ */
 fun createTodo(title: String) {
     val id = Lodash.uniqueId("todo_")
     val todo = Todo(id = id, title = title)
     putTodo(todo)
 }
 
+/**
+ * Toggles the completed state of the given [todo]
+ *
+ * This method is asynchronous and automatically redraws the UI on completion. In case of an error,
+ * the error is printed to the console and the UI is not updated.
+ */
 fun toggleTodo(todo: Todo) {
     putTodo(todo.copy(completed = !todo.completed))
 }

frontend/src/main/kotlin/coroutines.kt

@@ -1,14 +1,25 @@
 import kotlin.coroutines.experimental.*
 import kotlin.js.Promise
 
+/**
+ * Suspends the coroutine until the promise resolves, then returns its resolved value
+ */
 suspend fun <T> Promise<T>.await(): T = suspendCoroutine { cont ->
     then({ cont.resume(it) }, { cont.resumeWithException(it) })
 }
 
+/**
+ * Launches an asynchronous block as coroutine
+ *
+ * The block is executed with an empty context. If it throws an exception, the error is logged to
+ * the console.
+ */
 fun launch(block: suspend () -> Unit) {
     block.startCoroutine(object : Continuation<Unit> {
         override val context: CoroutineContext get() = EmptyCoroutineContext
         override fun resume(value: Unit) {}
-        override fun resumeWithException(e: Throwable) { console.log("Coroutine failed: $e") }
+        override fun resumeWithException(e: Throwable) {
+            console.log("Coroutine failed: $e")
+        }
     })
 }

frontend/src/main/kotlin/lodash.kt

@@ -1,4 +1,17 @@
+/**
+ * Binding to the native lodash implementation (installed via npm).
+ *
+ * This requires a module loader that can provide the "lodash" module, likely
+ * installed with "npm install lodash".
+ *
+ * Also, if webpack is configured correctly, tree shaking will make sure that
+ * all unused lodash functions get eliminated in the final bundle to reduce
+ * asset size.
+ */
 @JsModule("lodash")
 external object Lodash {
-    fun uniqueId(text: String = definedExternally): String;
+    /**
+     * Generates a unique ID. If prefix is given, the ID is appended to it
+     */
+    fun uniqueId(prefix: String = definedExternally): String;
 }

frontend/src/main/kotlin/main.kt

@@ -2,8 +2,19 @@ import kotlinx.html.dom.append
 import kotlin.browser.document
 import kotlin.browser.window
 
+/**
+ * Loads all Todos and renders the main UI
+ */
 suspend fun render() {
+    // Asynchronously fetch all TODOs from the server. We suspend until the response
+    // arrives, so we can immediately render the main UI. Usually, we would display
+    // a loading indicator here, so the user knows what's going on. Also, it makes
+    // sense to store TODOs in some local state so we don't have to fetch them every
+    // time we're rendering the App.
     val response = window.fetch("http://localhost:8080/todo/").await()
+
+    // It is important to transform plain JS objects to domain objects here
+    // Otherwise, we wouldn't be able to call instance methods on them later on
     val todos = mapJson(response.json().await(), ::deserializeTodo)
 
     // Remove any previous content
@@ -17,8 +28,13 @@ suspend fun render() {
     }
 }
 
+/**
+ * This is the main entry point of the Todo app. All imported files will be compiled
+ * into a single bundle by the kotlin2js compiler. Since we use certain methods from
+ * stdlib we also need to load kotlin.js during runtime.
+ */
 fun main(args: Array<String>) {
-    launch {
-        render()
-    }
+    // Since render is suspending, we need to call it in a coroutine context.
+    // This is handled by the launch helper
+    launch { render() }
 }

frontend/src/main/kotlin/serialization.kt

@@ -1,5 +1,21 @@
 import domain.Todo
 
+/**
+ * Converts a plain [json] object into a [Todo]
+ *
+ * Note that this function does not validate the JSON before converting.
+ * Incomplete data, such as a missing id or title could cause errors later
+ * in the program. Kotlin does not runime-check dynamic values at all.
+ */
 fun deserializeTodo(json: dynamic) = Todo(json.id, json.title, json.text, json.completed)
 
+/**
+ * Converts a plain [json] object into an array of [Todo]s.
+ *
+ * Note that this function does not validate the JSON before converting. The
+ * cast to Array<T> is unsafe and will always succeed. Calling map on the
+ * result can crash during runtime, however, if the [json] parameter does
+ * not implement a compatible map method. Kotlin neither runtime-checks the
+ * cast nor the result type.
+ */
 fun <T> mapJson(json: dynamic, transform: (dynamic) -> T) = (json as Array<T>).map(transform)

frontend/src/main/kotlin/ui.kt

@@ -1,10 +1,12 @@
-
 import domain.Todo
 import kotlinx.html.*
 import kotlinx.html.js.onChangeFunction
 import kotlinx.html.js.onClickFunction
 import org.w3c.dom.HTMLInputElement
 
+/**
+ * Renders a single [todo]
+ */
 fun <T, C : kotlinx.html.TagConsumer<T>> C.Todo(todo: Todo) = div {
     onClickFunction = { toggleTodo(todo) }
 
@@ -17,6 +19,9 @@ fun <T, C : kotlinx.html.TagConsumer<T>> C.Todo(todo: Todo) = div {
     }
 }
 
+/**
+ * Renders a list of [todos] and an input box to create new ones
+ */
 fun <T, C : kotlinx.html.TagConsumer<T>> C.Todos(todos: List<Todo>) = div {
     id = "todos"
 

frontend/src/main/resources/index.html

@@ -2,11 +2,10 @@
 <html lang="en">
 <head>
   <meta charset="UTF-8">
-  <meta name="viewport"
-    content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
   <meta http-equiv="X-UA-Compatible" content="ie=edge">
 
-  <title>Document</title>
+  <title>Todos</title>
 
   <link rel="stylesheet" href="http://todomvc.com/examples/react/node_modules/todomvc-app-css/index.css">
   <style>
@@ -22,6 +21,7 @@
   </style>
 </head>
 <body class="todoapp">
+  <!-- The URL could be injected during build time -->
   <script src="../../bundle/main.bundle.js"></script>
 </body>
 </html>

frontend/webpack.config.d/minify.js

@@ -3,7 +3,15 @@ if (defined.PRODUCTION) {
   config.plugins.push(new webpack.optimize.ModuleConcatenationPlugin());
   config.plugins.push(new webpack.optimize.UglifyJsPlugin({ minimize: true }));
 
-  // Use minified output form kotlin-dce-js
+  // Use minified output form kotlin-dce-js. This patches webpack to look for
+  // minified output in the correct directory, as gradle will automatically move
+  // all assets to that folder.
   config.context += '/min';
+
+  // The kotlin frontend plugin does not know about dce-js and that it puts the
+  // minified kotlin.js in a different location. However, is set to a fixed
+  // file URL in the generated package.json (have a look in build/package.json
+  // to see where it points to). Therefore, we have to tell webpack's resolver
+  // where to look for the minified version instead.
   config.resolve.alias = { kotlin: config.context + '/kotlin.js' };
 }

settings.gradle

@@ -2,4 +2,3 @@ rootProject.name = 'kotlin-multi-todo'
 include 'frontend'
 include 'domain'
 include 'backend'
-