Merge pull request Kotlin#47 from p7nov/functional-revised

docs: revised Functional

Author: AlexanderPrendota

examples/04_functional/01_Higher-Order Functions.md

@@ -1,8 +1,8 @@
 # Higher-Order Functions
 
-A higher-order function is a function that takes another function as parameter and/or returns a function.
+A [*higher-order function*](https://kotlinlang.org/docs/reference/lambdas.html) is a function that takes another function as parameter and/or returns a function.
 
-### Taking a function as parameter
+### Taking Functions as Parameters
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -22,15 +22,13 @@ fun main() {
 
 </div>
 
-1. Declare a higher-order function that takes as parameter two integers, x and y. In addition it takes another function as parameter, named `operation`
-that itself takes two parameters of type integer and returns an integer.
-2. Invoke the function passing in the arguments supplied.
-3. Declare a function that matches the same signature.
-4. Invoke the higher-order function passing in as the function argument, `::sum` which is how we reference a function by name in Kotlin.
-5. Invoke the higher-order function passing in as function argument a lambda function. Looks more clear, doesn't it?
-
-### Returning a function as parameter
+1. Declares a higher-order function. It takes two integer parameters, `x` and `y`. Additionally, it takes another function `operation` as a parameter. The `operation` parameters and return type are also defined in the declaration.
+2. The higher order function returns the result of `operation` invocation with the supplied agruments.
+3. Declares a function that matches the `operation`signature.
+4. Invokes the higher-order function passing in two integer values and the function argument `::sum`. `::` is the notation that references a function by name in Kotlin.
+5. Invokes the higher-order function passing in a lambda as a function argument. Looks clearer, doesn't it?
 
+### Returning Functions
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -49,8 +47,8 @@ fun main() {
 
 </div>
 
-1. Declare a higher-order function that returns a function.
-2. Return a function matching the signature.
-3. Invoke `operation` to get the result assigned to a variable.
-4. Invoke the function.
+1. Declares a higher-order function that returns a function.
+2. Declares a function matching the signature.
+3. Invokes `operation` to get the result assigned to a variable. Here `func` becomes `square` which is returned by `operation`.
+4. Invokes `func`. The `square` function is actually executed.
 

examples/04_functional/02_Lambdas.md

@@ -1,6 +1,6 @@
 # Lambda Functions
 
-Lambda functions ("lambdas") are a simple way to create functions ad-hoc. Lambdas can be denoted very concisely in many cases thanks to type inference and the implicit `it` variable.
+[*Lambda functions*](https://kotlinlang.org/docs/reference/lambdas.html) ("lambdas") are a simple way to create functions ad-hoc. Lambdas can be denoted very concisely in many cases thanks to type inference and the implicit `it` variable.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -34,8 +34,8 @@ fun main() {
 </div>
 
 1. A lambda in all its glory, with explicit types everywhere. The lambda is the part in curly braces, which is assigned to a variable of type `(String) -> String` (a function type).
-2. Type inference inside lambda: infers type of lambda parameter from type of the variable it's assigned to.
-3. Type inference outside lambda: infers type of the variable based on the type of the lambda parameter and return value.
+2. Type inference inside lambda: the type of the lambda parameter is inferred from the type of the variable it's assigned to.
+3. Type inference outside lambda: the type of the variable is inferred from the type of the lambda parameter and return value.
 4. You cannot do both together, the compiler has no chance to infer the type that way.
-5. For lambdas with a single parameter, you don't have to explicitly name it. Instead, you can use the implicit `it` variable. This is especially useful whenever the type of `it` can be inferred (which is often the case).
-6. If your lambda just consists of a single function call, you may prefer function pointers.
+5. For lambdas with a single parameter, you don't have to explicitly name it. Instead, you can use the implicit `it` variable. This is especially useful when the type of `it` can be inferred (which is often the case).
+6. If your lambda consists of a single function call, you may use function pointers (`::`) .

examples/04_functional/03_extensionFunctions.md

@@ -1,5 +1,7 @@
 # Extension Functions and Properties
 
+Kotlin lets you add new members to any class with the [extensions](https://kotlinlang.org/docs/reference/extensions.html) mechanism. Namely, there are two types of extensions: extension functions and extension properties. They look a lot like normal functions and properties but with one important difference: you need to specify the type that you extend.
+
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
@@ -17,23 +19,22 @@ fun main() {
 
     val order = Order(listOf(Item("Bread", 25.0F), Item("Wine", 29.0F), Item("Water", 12.0F)))
 
-    println("Max priced item name: ${order.maxPricedItemName()}")
+    println("Max priced item name: ${order.maxPricedItemName()}")                     // 4
     println("Max priced item value: ${order.maxPricedItemValue()}")
-    println("Items: ${order.commaDelimitedItemNames}")
+    println("Items: ${order.commaDelimitedItemNames}")                                // 5
 
 }
 ```
 
 </div>
 
-1. We define simple models of `Item` and `Order`. `Order` can contain arbitrary `Collection` of `Item` s
-2. We define extension functions for `Order` type. Later we call these functions directly on the instance of that type. 
-3. We can also define extension properties.
-
-Read more about signature of [extensions](https://kotlinlang.org/docs/reference/extensions.html). Signature
-is very much like standard function or property signature, with addition that we need to specify type we're attaching function or property to.
+1. Defines simple models of `Item` and `Order`. `Order` can contain a collection of `Item` objects.
+2. Adds extension functions for the `Order` type.  
+3. Adds an extension property for the `Order` type.
+4. Calls extension functions directly on an instance of `Order`.
+5. Accesses the extension property on an instance of `Order`.
 
-It is even possible to execute extensions on `null` references. In their implementation we can check for `null` reference and based on that we can do any arbitrary logic. Example:
+It is even possible to execute extensions on `null` references. In an extension function, you can check the object for `null` and use the result in your code:
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">