Ale review

docs/topics/control-flow.md

@@ -27,10 +27,12 @@ fun main() {
     // You can also use `else if` in expressions:
     val maxLimit = 1
     val maxOrLimit = if (maxLimit > a) maxLimit else if (a > b) a else b
-
-    //sampleEnd
+
     println("max is $max")
+    // max is 3
     println("maxOrLimit is $maxOrLimit")
+    // maxOrLimit is 3
+    //sampleEnd
 }
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="if-else-if-kotlin"}
@@ -52,7 +54,7 @@ assigning it to a variable, the `else` branch is mandatory.
 
 ## When expressions and statements
 
-`when` is a conditional expression that executes code based on multiple possible values or conditions. It is
+`when` is a conditional expression that runs code based on multiple possible values or conditions. It is
 similar to the `switch` statement in Java, C, and similar languages. For example:
 
 ```kotlin
@@ -64,6 +66,7 @@ fun main() {
         2 -> print("x == 2")
         else -> print("x is neither 1 nor 2")
     }
+    // x == 2
     //sampleEnd
 }
 ```
@@ -72,7 +75,7 @@ fun main() {
 `when` matches its argument against all branches sequentially until some branch condition is satisfied.
 
 You can use `when` in a few different ways. Firstly, you can use `when` either as an **expression** or as a **statement**.
-As an expression, `when` returns a value that you can use later in your code. As a statement, `when` completes an action
+As an expression, `when` returns a value for later use in your code. As a statement, `when` completes an action
 without returning anything of further use:
 
 <table>
@@ -110,7 +113,9 @@ when (x) {
 </tr>
 </table>
 
-Secondly, you can use `when` with or without a subject.
+Secondly, you can use `when` with or without a subject. Whether you use a subject with `when` or not, your expression or
+statement behaves the same. We recommend using `when`with a subject when possible, as it makes your code easier to read
+and maintain by clearly showing what you're checking.
 
 <table>
    <tr>
@@ -135,15 +140,11 @@ when { ... }
 </tr>
 </table>
 
-> Where possible, we recommend using `when` with a subject. Using `when` with a subject makes your code easier to read
-> and maintain by clearly showing what is being checked.
-> 
-{style="note"}
-
 Depending on how you use `when`, there are different requirements for whether you need to cover all possible cases in your
 branches.
 
-If you use `when` as a statement, you don't have to cover all possible cases:
+If you use `when` as a statement, you don't have to cover all possible cases. In this example, some cases aren't covered,
+so nothing happens. However, no error occurs:
 
 ```kotlin
 fun main() {
@@ -154,6 +155,7 @@ fun main() {
         1 -> print("x == 1")
         2 -> print("x == 2")
     }
+    // x == 2
     //sampleEnd
 }
 ```
@@ -162,8 +164,9 @@ fun main() {
 In a `when` statement, the values of individual branches are ignored. Just like with `if`, each branch can be a block, 
 and its value is the value of the last expression in the block.
 
-If you use `when` as an expression, you have to cover all possible cases. The value of the first matching branch becomes
-the value of the overall expression. If you don't cover all cases, the compiler throws an error.
+If you use `when` as an expression, you have to cover all possible cases. In other words, it must be _exhaustive_.
+The value of the first matching branch becomes the value of the overall expression. If you don't cover all cases, 
+the compiler throws an error.
 
 If your `when` expression has a subject, you can use an `else` branch to make sure that all possible cases are covered, but
 it isn't mandatory. For example, if your subject is a `Boolean`, [`enum` class](enum-classes.md), [`sealed` class](sealed-classes.md),
@@ -192,8 +195,8 @@ when {
 }
 ```
 
-`when` expressions and statements can be used in a number of different ways to simplify your code, handle multiple conditions,
-and perform type checks.
+`when` expressions and statements offer different ways to simplify your code, handle multiple conditions, and perform 
+type checks.
 
 You can define a common behavior for multiple cases by combining their conditions in a single line with a comma: 
 
@@ -224,7 +227,7 @@ when (x) {
 }
 ```
 
-Additionally, you can check that a value `is` or `!is` a particular type. Note that,
+Additionally, you can check that a value is or isn't a particular type via the `is` or `!is` keywords. Note that,
 due to [smart casts](typecasts.md#smart-casts), you can access the member functions and properties of the type without
 any additional checks.
 
@@ -236,7 +239,7 @@ fun hasPrefix(x: Any) = when(x) {
 ```
 
 You can use `when` as a replacement for an `if`-`else` `if` chain.
-If there's no subject, the branch conditions are simply boolean expressions, and a branch is executed when its condition is true:
+If there's no subject, the branch conditions are simply boolean expressions, and a branch is run when its condition is true:
 
 ```kotlin
 when {
@@ -289,11 +292,12 @@ To iterate over a range of numbers, use a [range expression](ranges.md):
 fun main() {
 //sampleStart
     for (i in 1..3) {
-        println(i)
+        print(i)
     }
     for (i in 6 downTo 0 step 2) {
-        println(i)
+        print(i)
     }
+    // 1236420
 //sampleEnd
 }
 ```
@@ -308,8 +312,9 @@ fun main() {
 val array = arrayOf("a", "b", "c")
 //sampleStart
     for (i in array.indices) {
-        println(array[i])
+        print(array[i])
     }
+    // abc
 //sampleEnd
 }
 ```
@@ -324,18 +329,21 @@ fun main() {
     for ((index, value) in array.withIndex()) {
         println("the element at $index is $value")
     }
+    // the element at 0 is a
+    // the element at 1 is b
+    // the element at 2 is c
 //sampleEnd
 }
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
 ## While loops
 
-`while` and `do-while` loops execute their body continuously while their condition is satisfied.
+`while` and `do-while` loops process their body continuously while their condition is satisfied.
 The difference between them is the condition checking time:
-* `while` checks the condition and, if it's satisfied, executes the body and then returns to the condition check.
-* `do-while` executes the body and then checks the condition. If it's satisfied, the loop repeats. So, the body of `do-while`
-executes at least once regardless of the condition. 
+* `while` checks the condition and, if it's satisfied, processes the body and then returns to the condition check.
+* `do-while` processes the body and then checks the condition. If it's satisfied, the loop repeats. So, the body of `do-while`
+runs at least once regardless of the condition. 
 
 ```kotlin
 while (x > 0) {