Merge pull request Kotlin#45 from p7nov/controlflow-revised

docs: revised Control Flow

Author: AlexanderPrendota

examples/02_control_flow/01_When.md

@@ -1,6 +1,8 @@
 # When
 
-Kotlin does not have `switch` statement, instead of it it has more smart and clear `when` construction. Let's take a look
+Instead of the widely used `switch` statement, Kotlin provides the more flexible and clear `when` construction. It can be used either as a statement or as an expression.
+
+## When Statement
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -13,24 +15,57 @@ fun main() {
     cases("hello")
 }
 
-fun cases(obj: Any) {
+fun cases(obj: Any) {                                // 1
     when (obj) {
-        1 -> println("One")                          // 1
-        "Hello" -> println("Greeting")               // 2
-        is Long -> println("Long")                   // 3
-        !is String -> println("Not a string")        // 4
-        else -> println("Unknown")                   // 5
-    }
+        1 -> println("One")                          // 2
+        "Hello" -> println("Greeting")               // 3
+        is Long -> println("Long")                   // 4
+        !is String -> println("Not a string")        // 5
+        else -> println("Unknown")                   // 6
+    }   
 }
 
 class MyClass
 ```
 
 </div>
 
+1. This is a `when` statement. 
+2. Checks whether `obj` equals to one.
+3. Checks whether `obj` equals to `Hello`.
+4. Performs type checking.
+5. Performs inverse type checking.
+6. Default statement (might be omitted).
+
+Note that all branch conditions are checked sequentially until one of them is satisfied. So, only the first suitable branch will be executed.   
+
+## When Expresion
+
+<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+fun main() {
+    println(whenAssign("Hello"))
+    println(whenAssign(3.4))
+    println(whenAssign(1))
+    println(whenAssign(MyClass()))
+}
+
+fun whenAssign(obj: Any): Any {
+    val result = when (obj) {                   // 1
+        1 -> "one"                              // 2
+        "Hello" -> 1                            // 3
+        is Long -> false                        // 4
+        else -> 42                              // 5
+    }
+    return result
+}
+```
+
+</div>
 
-1. Check whether `obj` equals to `1`
-2. Check for string
-3. Or even instance check
-4. Negative instance check
-5. Default statement (might be omitted)
+1. This is a `when` expression. 
+2. Sets the value to `"one"` if `obj` equals to one.
+3. Sets the value to one if `obj` equals to `Hello`.
+4. Sets the value to `false` if `obj` is an instance of `Long`.
+5. Sets the value "42" if none of the previous conditions are satisfied. Unlike in `when` _statement_, the default branch is usually required in `when` _expression_, except the case when the compiler can check that other branches cover all possible cases.

examples/02_control_flow/02_Loops.md

@@ -1,6 +1,10 @@
 #Loops
 
-### for, while, do-while
+Kotlin supports all the commonly used loops: `for`, `while`, `do-while`
+
+### `for`
+
+`for` in Kotlin works the same way as in most languages.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -19,7 +23,11 @@ fun main(args: Array<String>) {
 
 </div>
 
-1. Loops through each cake in the list
+1. Loops through each cake in the list.
+
+### `while` and `do-while`
+
+`while` and `do-while` constructs work similarly to most languages as well.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -46,13 +54,13 @@ fun main(args: Array<String>) {
 
 </div>
 
-While and do-while constructs work similarly to most languages.
-
-1. Performs the block while the condition is true.
-2. Performs the block first, and then loops while evaluating the while condition.
+1. Executes the block while the condition is true.
+2. Executes the block first and then checking the condition.
 
 ### Iterators
 
+You can define your own iterators in your classes by implementing the `iterator` operator in them.
+
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
@@ -78,10 +86,10 @@ fun main() {
 
 </div>
 
-1. Providing an iterator implementation (marked with operator modifier).
-2. Returns the iterator for the list, which meets the method requirements
-    1. next(): Animal
-    2. hasNext(): Boolean
-3. Loops through each animal in the zoo
+1. Defines an iterator in a class. It must be named `iterator` and have the `operator` modifier.
+2. Returns the iterator that meets the following method requirements:
+  * `next()`: `Animal`
+  * `hasNext()`: `Boolean`
+3. Loops through animals in the zoo with the user-defined iterator.
 
-The iterator can be declared on the type or as an extension function.
+The iterator can be declared in the type or as an extension function.

examples/02_control_flow/03_Ranges.md

@@ -1,5 +1,7 @@
 # Ranges
 
+There is a set of tools for defining ranges in Kotlin. Let's have a brief look at them.
+
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
@@ -15,29 +17,61 @@ fun main() {
     }
     print(" ")
 
-    for (c in 'a'..'d') {        // 3
-        print(c)
+    for (i in 3 downTo 0) {      // 3
+        print(i)
     }
     print(" ")
 
-    for (c in 'a'..'g' step 2) { // 4
+//sampleEnd
+}
+```
+
+</div>
+
+1. Iterates over a range starting from 0 up to 3 (inclusive).
+2. Iterates over a range with a custom increment step for consecutive elements.
+5. Iterates over a range in _reverse_ order.
+
+Char ranges are also supported: 
+
+<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+fun main() {
+//sampleStart
+    for (c in 'a'..'d') {        // 1
         print(c)
     }
     print(" ")
 
-    for (i in 3 downTo 0) {      // 5
-        print(i)
+    for (c in 'z' downTo 's' step 2) { // 2
+        print(c)
     }
     print(" ")
 
+//sampleEnd
+}
+```
+
+</div>
+
+1. Iterates over a char range in alphabetical order.
+2. Char ranges support `step` and `downTo` as well.
+
+Ranges are also useful in `if` statements:
+
+<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+fun main() {
+//sampleStart
     val x = 2
-    if (x in 1..10) {            // 6
+    if (x in 1..10) {            // 1
         print(x)
     }
     print(" ")
 
-    val y = 3
-    if (y !in 1..4) {            // 7
+    if (x !in 1..4) {            // 2
         print(y)
     }
 //sampleEnd
@@ -46,11 +80,5 @@ fun main() {
 
 </div>
 
-1. Create range starting from 0 up to 3 (inclusive) and iterate over it
-2. You can define increment step for consecutive elements
-3. Char ranges can be created as well
-4. Increment step for char ranges are also valid
-5. To create a range in _reverse_ order use `downTo()` function
-6. Ranges are also useful in `if` statements
-7. `!in` is opposite of `in`. Statement is equal to `_false_`
-
+1. Checks if a value is in the range.
+2. `!in` is the opposite of `in`.

examples/02_control_flow/05_Conditional expression.md

@@ -1,7 +1,6 @@
 # Conditional Expression
 
-There is no ternary operator (condition ? then : else) in Kotlin instead `if` expression could be used in the same way.
-Let's take a look
+There is no ternary operator `condition ? then : else` in Kotlin. Instead, `if` may be used as an expression:
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -17,4 +16,4 @@ fun main() {
 
 </div>
 
-1. `if` is an expression, i.e. it returns a value.
+1. `if` is an expression here: it returns a value.