Merge pull request Kotlin#50 from p7nov/delegation-revised

docs: revised Delegation

Author: AlexanderPrendota

examples/07_Delegation/01_delegationPattern.md

@@ -1,25 +1,27 @@
 # Delegation Pattern
 
+Kotlin supports easy implementation of the [delegation pattern](https://kotlinlang.org/docs/reference/delegation.html) on the native level without any boilerplate code.
+
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
-interface SoundBehaviour {                                                          // 1
+interface SoundBehavior {                                                          // 1
     fun makeSound()
 }
 
-class ScreamBehavior(val n:String): SoundBehaviour {                                // 2
+class ScreamBehavior(val n:String): SoundBehavior {                                // 2
     override fun makeSound() = println("${n.toUpperCase()} !!!")
 }
 
-class RockAndRollBehavior(val n:String): SoundBehaviour {                           // 2
+class RockAndRollBehavior(val n:String): SoundBehavior {                           // 2
     override fun makeSound() = println("I'm The King of Rock 'N' Roll: $n")
 }
 
 // Tom Araya is the "singer" of Slayer
-class TomAraya(n:String): SoundBehaviour by ScreamBehavior(n)                       // 3
+class TomAraya(n:String): SoundBehavior by ScreamBehavior(n)                       // 3
 
 // You should know ;)
-class ElvisPresley(n:String): SoundBehaviour by RockAndRollBehavior(n)              // 3
+class ElvisPresley(n:String): SoundBehavior by RockAndRollBehavior(n)              // 3
 
 fun main() {
     val tomAraya = TomAraya("Trash Metal")
@@ -31,12 +33,10 @@ fun main() {
 
 </div>
 
-In Kotlin it's easy to delegate method calls without any boilerplate.
 
-1.  The interface SoundBehaviour is defined. Later there will be one class that implements the method and another will 
-    also have the interface, but just delegates the method call.
-2.  The class ScreamBehavior and RockAndRollBehavior actually implement the method.
-3.  The class TomAraya and ElvisPresley just delegate the methods defined by the interface SoundBehaviour to the 
-    responsible implementation. But does not need any boilerplate to delegate the method call at all.
-4.  Call makeSound() on tomAraya of type TomAraya or elvisPresley of type ElvisPresley and it is delegated to the
-    associated class
+1.  Defines the interface `SoundBehavior` with one method. 
+2.  The classes `ScreamBehavior` and `RockAndRollBehavior` implement the interface and contain their own implementations of the method.
+3.  The classes `TomAraya` and `ElvisPresley` also implement the interface, but not the method. Instead, they delegate the method calls to the 
+    responsible implementation. The delegate object is defined after the `by` keyword. As you see, no boilerplate code is required.
+4.  When `makeSound()` is called on `tomAraya` of type `TomAraya` or `elvisPresley` of type `ElvisPresley`, the call is delegated to the
+    corresponding delegate object.

examples/07_Delegation/02_DelegatedProperties.md

@@ -1,12 +1,7 @@
 # Delegated Properties
 
-There's some new syntax: you can say `val 'property name': 'Type' by 'expression'`.
-The expression after `by` is the delegate, because `get()` and `set()` methods
-corresponding to the property will be delegated to it.
-Property delegates don't have to implement any interface, but they have
-to provide methods named `getValue()` and `setValue()` to be called. The full documentation is [here](http://kotlinlang.org/docs/reference/delegated-properties.html). 
-
-Let's try some code.
+Kotlin provides a mechanism of [delegated properties](http://kotlinlang.org/docs/reference/delegated-properties.html) that allows delegating the calls of the property `set` and `get` methods to a certain object.
+The delegate object in this case should have the method `getValue`. For mutable properties, you'll also need `setValue`.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -38,47 +33,46 @@ fun main() {
 
 </div>
 
-1. Delegated property `p` of type `String`
-2. Delegation methods. For immutable property only `getValue` is required.
-
-### Standard delegates 
+1. Delegates property `p` of type `String` to the instance of class `Delegate`. The delegate object is defined after the `by` keyword.
+2. Delegation methods. The signatures of these methods are always as shown in the example. Implementations may contain any steps you need. For immutable properties only `getValue` is required.
 
-Kotlin standard library contains bunch of useful delegates, like `lazy`, `observable`, etc.
+### Standard Delegates 
 
-For example `lazy` is used in case lazy initialization.
+The Kotlin standard library contains a bunch of useful delegates, like `lazy`, `observable`, and other. You may use them as is.
+For example `lazy`is used for lazy initialization.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
 class LazySample {
     init {
-      println("created!");            // 1
+      println("created!")            // 1
     }
 
-    val lazy: String by lazy {
+    val lazyStr: String by lazy {
         println("computed!")          // 2
         "my lazy"
     }
 }
 
 fun main() {
     val sample = LazySample()         // 1
-    println("lazy = ${sample.lazy}")  // 2
-    println("lazy = ${sample.lazy}")  // 3
+    println("lazyStr = ${sample.lazyStr}")  // 2
+    println(" = ${sample.lazyStr}")  // 3
 }
 ```
 
 </div>
 
  1. Property `lazy` is not initialized on object creation.
- 2. The first call to `get()` executes the lambda expression passed to lazy() as an argument and remembers the result
- 3. Subsequent calls to `get()` simply return the remembered result.
+ 2. The first call to `get()` executes the lambda expression passed to `lazy()` as an argument and saves the result.
+ 3. Further calls to `get()` return the saved result.
 
-If you want thread safety, use blockingLazy() instead: it guarantees that the values will be computed only in one thread, and that all threads will see the same value.
+If you want thread safety, use `blockingLazy()` instead: it guarantees that the values will be computed only in one thread and that all threads will see the same value.
 
-### Properties in map
+### Storing Properties in a Map
 
-Properties stored in a map. This comes up a lot in applications like parsing JSON
+Property delegation can be used for storing properties in a map. This is handy for tasks like parsing JSON
 or doing other "dynamic" stuff.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
@@ -101,6 +95,6 @@ fun main() {
 
 </div>
 
-1. Delegates take values from the `map` (by the string keys - names of properties).
+1. Delegates take values from the `map` by the string keys - names of properties.
 
-Of course, you can have mutable property as well, that will modify the map upon assignment (note that you'd need `MutableMap` instead of read-only `Map`).
+You can delegate mutable properties to a map as well. In this case, the map will be modified upon property assignments. Note that you will need `MutableMap` instead of read-only `Map`.