Merge pull request #5 from PandoraMedia/additional-comments

Add additional explanation commentary.

src/main/kotlin/cancel/KtCancel.kt

@@ -29,13 +29,13 @@ class KtCancel (
         val job = launch { longRunningFunction() }
 
         launch {
-            delay(5000) // wait 5 seconds
-            job.cancel()
+            delay(5000) // wait 5 seconds,
+            job.cancel() // then cancel the running coroutine
         }
     }
 
     suspend fun longRunningFunction() {
-        while (isActive) {
+        while (isActive) { // check that the coroutine has not been canceled
             println("Long running job still active in KtCancel")
             delay(timeDelay)
         }

src/main/kotlin/cancel/RxCancel.kt

@@ -25,22 +25,22 @@ private const val timeDelay = 1000L
 class RxCancel (
     scheduler: Scheduler = Schedulers.computation()
 ) {
-    val stream = Flowable.interval(timeDelay, TimeUnit.MILLISECONDS)
+    val stream = Flowable.interval(timeDelay, TimeUnit.MILLISECONDS) // Once every second...
         .observeOn(scheduler)
         .map {
-            "Long running job still active in RxCancel"
+            "Long running job still active in RxCancel" // emit this string
         }
 
     init {
         val disposable = stream.subscribe({
-            println(it)
+            println(it) // log every emission to the console
         })
 
         Completable.fromAction {
-            disposable.dispose()
+            disposable.dispose() // throw away our subscription to the stream, canceling it
         }
-            .observeOn(scheduler)
-            .delaySubscription(5000, TimeUnit.MILLISECONDS)
-            .subscribe()
+        .observeOn(scheduler)
+        .delaySubscription(5000, TimeUnit.MILLISECONDS) // Wait 5 seconds, then subscribe (for demonstration purposes)
+        .subscribe()
     }
 }

src/main/kotlin/completable/KtCompletable.kt

@@ -26,7 +26,7 @@ class KtCompletable(
 ): CoroutineScope {
 
     init {
-        launch {
+        launch { // Since the encapsulating class extends CoroutineScope, we can simply use the launch coroutine builder to fire the work as a child of the current scope
             doSomeWork()
         }
     }

src/main/kotlin/filter/KtFilter.kt

@@ -34,8 +34,8 @@ class KtFilter (
 
     init {
         launch {
-            producer.filter { it % 2 == 0 }
-            .consumeEach {
+            producer.filter { it % 2 == 0 } // the .filter operator here will only send even numbers downstream
+            .consumeEach { // consumeEach subscribes to the producer Channel
                 println("Value from KtFilter: $it")
             }
         }

src/main/kotlin/merge/KtMerge.kt

@@ -29,7 +29,7 @@ class KtMerge(
 
     init {
         launch {
-            flowOf(flowOne, flowTwo).flattenMerge().collect {
+            flowOf(flowOne, flowTwo).flattenMerge().collect { // without the flattenMerge() we'd have a flow of flows rather than a flow of Ints
                 println("Value from KtMerge $it")
             }
         }