Flow docs (#1432)

* Flow guide by example

* Consistent chapter naming and ordering in docs
* Make "supervision" a subsection of "Exception Handling" chapter
* Knit: filter out sampleStart/End from Knit-generated source files
* Knit: Support example auto-numbering

Author: elizarov

coroutines-guide.md

@@ -3,7 +3,7 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m
 ## Table of contents
 
 <!--- TOC_REF docs/basics.md -->
-* <a name='coroutine-basics'></a>[Coroutine basics](docs/basics.md#coroutine-basics)
+* <a name='coroutine-basics'></a>[Coroutine Basics](docs/basics.md#coroutine-basics)
   * <a name='your-first-coroutine'></a>[Your first coroutine](docs/basics.md#your-first-coroutine)
   * <a name='bridging-blocking-and-non-blocking-worlds'></a>[Bridging blocking and non-blocking worlds](docs/basics.md#bridging-blocking-and-non-blocking-worlds)
   * <a name='waiting-for-a-job'></a>[Waiting for a job](docs/basics.md#waiting-for-a-job)
@@ -13,22 +13,22 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m
   * <a name='coroutines-are-light-weight'></a>[Coroutines ARE light-weight](docs/basics.md#coroutines-are-light-weight)
   * <a name='global-coroutines-are-like-daemon-threads'></a>[Global coroutines are like daemon threads](docs/basics.md#global-coroutines-are-like-daemon-threads)
 <!--- TOC_REF docs/cancellation-and-timeouts.md -->
-* <a name='cancellation-and-timeouts'></a>[Cancellation and timeouts](docs/cancellation-and-timeouts.md#cancellation-and-timeouts)
+* <a name='cancellation-and-timeouts'></a>[Cancellation and Timeouts](docs/cancellation-and-timeouts.md#cancellation-and-timeouts)
   * <a name='cancelling-coroutine-execution'></a>[Cancelling coroutine execution](docs/cancellation-and-timeouts.md#cancelling-coroutine-execution)
   * <a name='cancellation-is-cooperative'></a>[Cancellation is cooperative](docs/cancellation-and-timeouts.md#cancellation-is-cooperative)
   * <a name='making-computation-code-cancellable'></a>[Making computation code cancellable](docs/cancellation-and-timeouts.md#making-computation-code-cancellable)
   * <a name='closing-resources-with-finally'></a>[Closing resources with `finally`](docs/cancellation-and-timeouts.md#closing-resources-with-finally)
   * <a name='run-non-cancellable-block'></a>[Run non-cancellable block](docs/cancellation-and-timeouts.md#run-non-cancellable-block)
   * <a name='timeout'></a>[Timeout](docs/cancellation-and-timeouts.md#timeout)
 <!--- TOC_REF docs/composing-suspending-functions.md -->
-* <a name='composing-suspending-functions'></a>[Composing suspending functions](docs/composing-suspending-functions.md#composing-suspending-functions)
+* <a name='composing-suspending-functions'></a>[Composing Suspending Functions](docs/composing-suspending-functions.md#composing-suspending-functions)
   * <a name='sequential-by-default'></a>[Sequential by default](docs/composing-suspending-functions.md#sequential-by-default)
   * <a name='concurrent-using-async'></a>[Concurrent using async](docs/composing-suspending-functions.md#concurrent-using-async)
   * <a name='lazily-started-async'></a>[Lazily started async](docs/composing-suspending-functions.md#lazily-started-async)
   * <a name='async-style-functions'></a>[Async-style functions](docs/composing-suspending-functions.md#async-style-functions)
   * <a name='structured-concurrency-with-async'></a>[Structured concurrency with async](docs/composing-suspending-functions.md#structured-concurrency-with-async)
 <!--- TOC_REF docs/coroutine-context-and-dispatchers.md -->
-* <a name='coroutine-context-and-dispatchers'></a>[Coroutine context and dispatchers](docs/coroutine-context-and-dispatchers.md#coroutine-context-and-dispatchers)
+* <a name='coroutine-context-and-dispatchers'></a>[Coroutine Context and Dispatchers](docs/coroutine-context-and-dispatchers.md#coroutine-context-and-dispatchers)
   * <a name='dispatchers-and-threads'></a>[Dispatchers and threads](docs/coroutine-context-and-dispatchers.md#dispatchers-and-threads)
   * <a name='unconfined-vs-confined-dispatcher'></a>[Unconfined vs confined dispatcher](docs/coroutine-context-and-dispatchers.md#unconfined-vs-confined-dispatcher)
   * <a name='debugging-coroutines-and-threads'></a>[Debugging coroutines and threads](docs/coroutine-context-and-dispatchers.md#debugging-coroutines-and-threads)
@@ -40,16 +40,45 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m
   * <a name='combining-context-elements'></a>[Combining context elements](docs/coroutine-context-and-dispatchers.md#combining-context-elements)
   * <a name='coroutine-scope'></a>[Coroutine scope](docs/coroutine-context-and-dispatchers.md#coroutine-scope)
   * <a name='thread-local-data'></a>[Thread-local data](docs/coroutine-context-and-dispatchers.md#thread-local-data)
-<!--- TOC_REF docs/exception-handling.md -->
-* <a name='exception-handling'></a>[Exception handling](docs/exception-handling.md#exception-handling)
-  * <a name='exception-propagation'></a>[Exception propagation](docs/exception-handling.md#exception-propagation)
-  * <a name='coroutineexceptionhandler'></a>[CoroutineExceptionHandler](docs/exception-handling.md#coroutineexceptionhandler)
-  * <a name='cancellation-and-exceptions'></a>[Cancellation and exceptions](docs/exception-handling.md#cancellation-and-exceptions)
-  * <a name='exceptions-aggregation'></a>[Exceptions aggregation](docs/exception-handling.md#exceptions-aggregation)
-* <a name='supervision'></a>[Supervision](docs/exception-handling.md#supervision)
-  * <a name='supervision-job'></a>[Supervision job](docs/exception-handling.md#supervision-job)
-  * <a name='supervision-scope'></a>[Supervision scope](docs/exception-handling.md#supervision-scope)
-  * <a name='exceptions-in-supervised-coroutines'></a>[Exceptions in supervised coroutines](docs/exception-handling.md#exceptions-in-supervised-coroutines)
+<!--- TOC_REF docs/flow.md -->
+* <a name='asynchronous-flow'></a>[Asynchronous Flow](docs/flow.md#asynchronous-flow)
+  * <a name='representing-multiple-values'></a>[Representing multiple values](docs/flow.md#representing-multiple-values)
+    * <a name='sequences'></a>[Sequences](docs/flow.md#sequences)
+    * <a name='suspending-functions'></a>[Suspending functions](docs/flow.md#suspending-functions)
+    * <a name='flows'></a>[Flows](docs/flow.md#flows)
+  * <a name='flows-are-cold'></a>[Flows are cold](docs/flow.md#flows-are-cold)
+  * <a name='flow-cancellation'></a>[Flow cancellation](docs/flow.md#flow-cancellation)
+  * <a name='flow-builders'></a>[Flow builders](docs/flow.md#flow-builders)
+  * <a name='intermediate-flow-operators'></a>[Intermediate flow operators](docs/flow.md#intermediate-flow-operators)
+    * <a name='transform-operator'></a>[Transform operator](docs/flow.md#transform-operator)
+    * <a name='size-limiting-operators'></a>[Size-limiting operators](docs/flow.md#size-limiting-operators)
+  * <a name='terminal-flow-operators'></a>[Terminal flow operators](docs/flow.md#terminal-flow-operators)
+  * <a name='flows-are-sequential'></a>[Flows are sequential](docs/flow.md#flows-are-sequential)
+  * <a name='flow-context'></a>[Flow context](docs/flow.md#flow-context)
+    * <a name='wrong-emission-withcontext'></a>[Wrong emission withContext](docs/flow.md#wrong-emission-withcontext)
+    * <a name='flowon-operator'></a>[flowOn operator](docs/flow.md#flowon-operator)
+  * <a name='buffering'></a>[Buffering](docs/flow.md#buffering)
+    * <a name='conflation'></a>[Conflation](docs/flow.md#conflation)
+    * <a name='processing-the-latest-value'></a>[Processing the latest value](docs/flow.md#processing-the-latest-value)
+  * <a name='composing-multiple-flows'></a>[Composing multiple flows](docs/flow.md#composing-multiple-flows)
+    * <a name='zip'></a>[Zip](docs/flow.md#zip)
+    * <a name='combine'></a>[Combine](docs/flow.md#combine)
+  * <a name='flattening-flows'></a>[Flattening flows](docs/flow.md#flattening-flows)
+    * <a name='flatmapconcat'></a>[flatMapConcat](docs/flow.md#flatmapconcat)
+    * <a name='flatmapmerge'></a>[flatMapMerge](docs/flow.md#flatmapmerge)
+    * <a name='flatmaplatest'></a>[flatMapLatest](docs/flow.md#flatmaplatest)
+  * <a name='flow-exceptions'></a>[Flow exceptions](docs/flow.md#flow-exceptions)
+    * <a name='collector-try-and-catch'></a>[Collector try and catch](docs/flow.md#collector-try-and-catch)
+    * <a name='everything-is-caught'></a>[Everything is caught](docs/flow.md#everything-is-caught)
+  * <a name='exception-transparency'></a>[Exception transparency](docs/flow.md#exception-transparency)
+    * <a name='transparent-catch'></a>[Transparent catch](docs/flow.md#transparent-catch)
+    * <a name='catching-declaratively'></a>[Catching declaratively](docs/flow.md#catching-declaratively)
+  * <a name='flow-completion'></a>[Flow completion](docs/flow.md#flow-completion)
+    * <a name='imperative-finally-block'></a>[Imperative finally block](docs/flow.md#imperative-finally-block)
+    * <a name='declarative-handling'></a>[Declarative handling](docs/flow.md#declarative-handling)
+    * <a name='upstream-exceptions-only'></a>[Upstream exceptions only](docs/flow.md#upstream-exceptions-only)
+    * <a name='imperative-versus-declarative'></a>[Imperative versus declarative](docs/flow.md#imperative-versus-declarative)
+  * <a name='launching-flow'></a>[Launching flow](docs/flow.md#launching-flow)
 <!--- TOC_REF docs/channels.md -->
 * <a name='channels'></a>[Channels](docs/channels.md#channels)
   * <a name='channel-basics'></a>[Channel basics](docs/channels.md#channel-basics)
@@ -62,6 +91,16 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m
   * <a name='buffered-channels'></a>[Buffered channels](docs/channels.md#buffered-channels)
   * <a name='channels-are-fair'></a>[Channels are fair](docs/channels.md#channels-are-fair)
   * <a name='ticker-channels'></a>[Ticker channels](docs/channels.md#ticker-channels)
+<!--- TOC_REF docs/exception-handling.md -->
+* <a name='exception-handling'></a>[Exception Handling](docs/exception-handling.md#exception-handling)
+  * <a name='exception-propagation'></a>[Exception propagation](docs/exception-handling.md#exception-propagation)
+  * <a name='coroutineexceptionhandler'></a>[CoroutineExceptionHandler](docs/exception-handling.md#coroutineexceptionhandler)
+  * <a name='cancellation-and-exceptions'></a>[Cancellation and exceptions](docs/exception-handling.md#cancellation-and-exceptions)
+  * <a name='exceptions-aggregation'></a>[Exceptions aggregation](docs/exception-handling.md#exceptions-aggregation)
+  * <a name='supervision'></a>[Supervision](docs/exception-handling.md#supervision)
+    * <a name='supervision-job'></a>[Supervision job](docs/exception-handling.md#supervision-job)
+    * <a name='supervision-scope'></a>[Supervision scope](docs/exception-handling.md#supervision-scope)
+    * <a name='exceptions-in-supervised-coroutines'></a>[Exceptions in supervised coroutines](docs/exception-handling.md#exceptions-in-supervised-coroutines)
 <!--- TOC_REF docs/shared-mutable-state-and-concurrency.md -->
 * <a name='shared-mutable-state-and-concurrency'></a>[Shared mutable state and concurrency](docs/shared-mutable-state-and-concurrency.md#shared-mutable-state-and-concurrency)
   * <a name='the-problem'></a>[The problem](docs/shared-mutable-state-and-concurrency.md#the-problem)
@@ -72,7 +111,7 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m
   * <a name='mutual-exclusion'></a>[Mutual exclusion](docs/shared-mutable-state-and-concurrency.md#mutual-exclusion)
   * <a name='actors'></a>[Actors](docs/shared-mutable-state-and-concurrency.md#actors)
 <!--- TOC_REF docs/select-expression.md -->
-* <a name='select-expression-experimental'></a>[Select expression (experimental)](docs/select-expression.md#select-expression-experimental)
+* <a name='select-expression-experimental'></a>[Select Expression (experimental)](docs/select-expression.md#select-expression-experimental)
   * <a name='selecting-from-channels'></a>[Selecting from channels](docs/select-expression.md#selecting-from-channels)
   * <a name='selecting-on-close'></a>[Selecting on close](docs/select-expression.md#selecting-on-close)
   * <a name='selecting-to-send'></a>[Selecting to send](docs/select-expression.md#selecting-to-send)

docs/_nav.yml

@@ -7,21 +7,24 @@
 - md: cancellation-and-timeouts.md
   url: cancellation-and-timeouts.html
   title: Cancellation and Timeouts
-- md: channels.md
-  url: channels.html
-  title: Channels
 - md: composing-suspending-functions.md
   url: composing-suspending-functions.html
   title: Composing Suspending Functions
 - md: coroutine-context-and-dispatchers.md
   url: coroutine-context-and-dispatchers.html
   title: Coroutine Context and Dispatchers
+- md: flow.md
+  url: flow.html
+  title: Asynchronous Flow
+- md: channels.md
+  url: channels.html
+  title: Channels
 - md: exception-handling.md
   url: exception-handling.html
-  title: Exception Handling
-- md: select-expression.md
-  url: select-expression.html
-  title: Select Expression
+  title: Exception Handling and Supervision
 - md: shared-mutable-state-and-concurrency.md
   url: shared-mutable-state-and-concurrency.html
   title: Shared Mutable State and Concurrency
+- md: select-expression.md
+  url: select-expression.html
+  title: Select Expression (experimental)

docs/basics.md

@@ -20,7 +20,7 @@ class BasicsGuideTest {
 
 <!--- TOC -->
 
-* [Coroutine basics](#coroutine-basics)
+* [Coroutine Basics](#coroutine-basics)
   * [Your first coroutine](#your-first-coroutine)
   * [Bridging blocking and non-blocking worlds](#bridging-blocking-and-non-blocking-worlds)
   * [Waiting for a job](#waiting-for-a-job)
@@ -33,7 +33,7 @@ class BasicsGuideTest {
 <!--- END_TOC -->
 
 
-## Coroutine basics
+## Coroutine Basics
 
 This section covers basic coroutine concepts.
 

docs/cancellation-and-timeouts.md

@@ -19,7 +19,7 @@ class CancellationTimeOutsGuideTest {
 
 <!--- TOC -->
 
-* [Cancellation and timeouts](#cancellation-and-timeouts)
+* [Cancellation and Timeouts](#cancellation-and-timeouts)
   * [Cancelling coroutine execution](#cancelling-coroutine-execution)
   * [Cancellation is cooperative](#cancellation-is-cooperative)
   * [Making computation code cancellable](#making-computation-code-cancellable)
@@ -29,7 +29,7 @@ class CancellationTimeOutsGuideTest {
 
 <!--- END_TOC -->
 
-## Cancellation and timeouts
+## Cancellation and Timeouts
 
 This section covers coroutine cancellation and timeouts.
 

docs/composing-suspending-functions.md

@@ -20,7 +20,7 @@ class ComposingGuideTest {
 
 <!--- TOC -->
 
-* [Composing suspending functions](#composing-suspending-functions)
+* [Composing Suspending Functions](#composing-suspending-functions)
   * [Sequential by default](#sequential-by-default)
   * [Concurrent using async](#concurrent-using-async)
   * [Lazily started async](#lazily-started-async)
@@ -29,7 +29,7 @@ class ComposingGuideTest {
 
 <!--- END_TOC -->
 
-## Composing suspending functions
+## Composing Suspending Functions
 
 This section covers various approaches to composition of suspending functions.
 

docs/coroutine-context-and-dispatchers.md

@@ -20,7 +20,7 @@ class DispatchersGuideTest {
 
 <!--- TOC -->
 
-* [Coroutine context and dispatchers](#coroutine-context-and-dispatchers)
+* [Coroutine Context and Dispatchers](#coroutine-context-and-dispatchers)
   * [Dispatchers and threads](#dispatchers-and-threads)
   * [Unconfined vs confined dispatcher](#unconfined-vs-confined-dispatcher)
   * [Debugging coroutines and threads](#debugging-coroutines-and-threads)
@@ -35,7 +35,7 @@ class DispatchersGuideTest {
 
 <!--- END_TOC -->
 
-## Coroutine context and dispatchers
+## Coroutine Context and Dispatchers
 
 Coroutines always execute in some context represented by a value of the 
 [CoroutineContext](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines/-coroutine-context/) 

docs/coroutines-guide.md

@@ -15,14 +15,15 @@ In order to use coroutines as well as follow the examples in this guide, you nee
 
 ## Table of contents
 
-* [Coroutine basics](basics.md)
-* [Cancellation and timeouts](cancellation-and-timeouts.md)
-* [Composing suspending functions](composing-suspending-functions.md)
-* [Coroutine context and dispatchers](coroutine-context-and-dispatchers.md)
-* [Exception handling and supervision](exception-handling.md)
-* [Channels (experimental)](channels.md)
-* [Shared mutable state and concurrency](shared-mutable-state-and-concurrency.md)
-* [Select expression (experimental)](select-expression.md)
+* [Basics](basics.md)
+* [Cancellation and Timeouts](cancellation-and-timeouts.md)
+* [Composing Suspending Functions](composing-suspending-functions.md)
+* [Coroutine Context and Dispatchers](coroutine-context-and-dispatchers.md)
+* [Asynchronous Flow](flow.md)
+* [Channels](channels.md)
+* [Exception Handling and Supervision](exception-handling.md)
+* [Shared Mutable State and Concurrency](shared-mutable-state-and-concurrency.md)
+* [Select Expression (experimental)](select-expression.md)
 
 ## Additional references
 

docs/exception-handling.md

@@ -19,19 +19,19 @@ class ExceptionsGuideTest {
 
 <!--- TOC -->
 
-* [Exception handling](#exception-handling)
+* [Exception Handling](#exception-handling)
   * [Exception propagation](#exception-propagation)
   * [CoroutineExceptionHandler](#coroutineexceptionhandler)
   * [Cancellation and exceptions](#cancellation-and-exceptions)
   * [Exceptions aggregation](#exceptions-aggregation)
-* [Supervision](#supervision)
-  * [Supervision job](#supervision-job)
-  * [Supervision scope](#supervision-scope)
-  * [Exceptions in supervised coroutines](#exceptions-in-supervised-coroutines)
+  * [Supervision](#supervision)
+    * [Supervision job](#supervision-job)
+    * [Supervision scope](#supervision-scope)
+    * [Exceptions in supervised coroutines](#exceptions-in-supervised-coroutines)
 
 <!--- END_TOC -->
 
-## Exception handling
+## Exception Handling
 
 
 This section covers exception handling and cancellation on exceptions.
@@ -355,7 +355,7 @@ Caught original java.io.IOException
 ```
 <!--- TEST-->
 
-## Supervision
+### Supervision
 
 As we have studied before, cancellation is a bidirectional relationship propagating through the whole
 coroutines hierarchy. But what if unidirectional cancellation is required? 
@@ -367,7 +367,7 @@ but if UI component is destroyed (and its job is cancelled), then it is necessar
 Another example is a server process that spawns several children jobs and needs to _supervise_
 their execution, tracking their failures and restarting just those children jobs that had failed.
 
-### Supervision job
+#### Supervision job
 
 For these purposes [SupervisorJob][SupervisorJob()] can be used. It is similar to a regular [Job][Job()] with the only exception that cancellation is propagated
 only downwards. It is easy to demonstrate with an example:
@@ -421,7 +421,7 @@ Second child is cancelled because supervisor is cancelled
 <!--- TEST-->
 
 
-### Supervision scope
+#### Supervision scope
 
 For *scoped* concurrency [supervisorScope] can be used instead of [coroutineScope] for the same purpose. It propagates cancellation 
 only in one direction and cancels all children only if it has failed itself. It also waits for all children before completion
@@ -469,7 +469,7 @@ Caught assertion error
 ```
 <!--- TEST-->
 
-### Exceptions in supervised coroutines
+#### Exceptions in supervised coroutines
 
 Another crucial difference between regular and supervisor jobs is exception handling.
 Every child should handle its exceptions by itself via exception handling mechanisms.