Merge pull request Kotlin#46 from p7nov/special-classes-revised

docs: revised Special classes

Author: AlexanderPrendota

examples/03_special_classes/00_description.md

@@ -1 +1 @@
-# Special classes
+# Special Classes

examples/03_special_classes/01_Data classes.md

@@ -1,30 +1,27 @@
-# Data classes
+# Data Classes
 
-_Data classes_ make it easy to declare classes that are used to store some values.
-Everything that's needed to use them in collections, have a useful string
-representation, and create copies is auto-generated.
+[Data classes](https://kotlinlang.org/docs/reference/data-classes.html) make it easy to create classes that are used to store values. Such classes are automatically provided with methods for copying, getting a string representation, and using instances in collections.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
-data class User(val name: String, val id: Int)
+data class User(val name: String, val id: Int)            // 1
 
 fun main() {
     val user = User("Alex", 1)
-    println(user)                                          // 1
+    println(user)                                          // 2
 
     val secondUser = User("Alex", 1)
     val thirdUser = User("Max", 2)
 
-    println("user == secondUser: ${user == secondUser}")   // 2
+    println("user == secondUser: ${user == secondUser}")   // 3
     println("user == thirdUser: ${user == thirdUser}")
 
-    println(user.hashCode())                               // 3
+    println(user.hashCode())                               // 4
     println(thirdUser.hashCode())
 
     // copy() function
-    println(user.copy())                                   // 4
-    println(user.copy("Max", 2))                           // 5
+    println(user.copy())                                   // 5
     println(user.copy("Max"))                              // 6
     println(user.copy(id = 2))                             // 7
 
@@ -35,11 +32,11 @@ fun main() {
 
 </div>
 
-1. Method `toString` is auto-generated, which makes `println` output look nice.
-2. Auto-generated `equals` makes data classes with equal information equals as well.
-3. Equal data classes have equal `hashCode()`.
-4. Predefined `copy` function makes it easy to obtain a new instance.
-5. Property values can be changed on copy. The order corresponds to constructor argument order.
-6. It is possible to change only some values.
-7. Use named arguments to change the second value without altering the first one.
-8. Additionally special `componentN` functions are generated.
+1. Defines a data class with the `data` modifier. 
+2. Method `toString` is auto-generated, which makes `println` output look nice.
+3. Auto-generated `equals` considers two instances equal if all their properties are equal.
+4. Equal data class instances have equal `hashCode()`.
+5. Auto-generated `copy` function makes it easy to create a new instance.
+6. When copying, you can change values of certain properties. `copy` accepts areguments in the same order as the class constructor.
+7. Use `copy` with named arguments to change the value despite of the properties order.
+8. Auto-generated `componentN` functions let you get the values of properties in the order of declaration.

examples/03_special_classes/02_Enum.md

@@ -1,8 +1,6 @@
 # Enum Classes
 
-Enum classes are used to model types that represent a finite set of distinct values, such as directions, states, modes and so forth.
-
-They may contain properties and methods like other classes, separated from the enum instances by a semicolon.
+[Enum classes](https://kotlinlang.org/docs/reference/enum-classes.html) are used to model types that represent a finite set of distinct values, such as directions, states, modes, and so forth.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -11,38 +9,53 @@ enum class State {
     IDLE, RUNNING, FINISHED                           // 1
 }
 
-enum class Color(val rgb: Int) {                      // 2
-    RED(0xFF0000),                                    // 3
+fun main() {
+    val state = State.RUNNING                         // 2
+    val message = when (state) {                      // 3
+        State.IDLE -> "It's idle"
+        State.RUNNING -> "It's running"
+        State.FINISHED -> "It's finished"
+    }
+    println(message)
+}
+
+```
+
+</div>
+
+1. Defines a simple enum class with three enum instances. The number of instances is always finite and they are all distinct.
+2. Accesses an enum instance via the class name.
+3. With enums, the compiler can infer if a `when`-expression is exhaustive so that you don't need the `else`-case.
+
+Enums may contain properties and methods like other classes, separated from the list of instances by a semicolon.
+
+<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+
+enum class Color(val rgb: Int) {                      // 1
+    RED(0xFF0000),                                    // 2
     GREEN(0x00FF00),
     BLUE(0x0000FF),
     YELLOW(0xFFFF00);
 
-    fun containsRed() = (this.rgb and 0xFF0000 != 0)  // 4
+    fun containsRed() = (this.rgb and 0xFF0000 != 0)  // 3
 }
 
 fun main() {
-    val red = Color.RED                               // 5
-    println(red)                                      // 6
-    println(red.containsRed())
-    println(Color.BLUE.containsRed())
-
-    val state = State.RUNNING
-    val message = when (state) {                      // 7
-        State.IDLE -> "It's idle"
-        State.RUNNING -> "It's running"
-        State.FINISHED -> "It's finished"
-    }
-    println(message)
+    val red = Color.RED
+    println(red)                                      // 4
+    println(red.containsRed())                        // 5
+    println(Color.BLUE.containsRed())                 // 6
 }
 
 ```
 
 </div>
 
-1. A simple enum class with three enum instances (note that instances are finite and distinct).
-2. An enum class with a property and a method.
-3. Each instance must pass an argument for the constructor parameter.
-4. Members are separated from the instance definitions with a semicolon.
-5. Enum instances are accessed directly via the class name.
-6. The default `toString` returns the name of the instance, here `"RED"`.
-7. With enums, the compiler can infer if a `when`-expression is exhaustive so that you don't need an `else`-case.
+1. Defines an enum class with a property and a method.
+2. Each instance must pass an argument for the constructor parameter.
+3. Enum class members are separated from the instance definitions by a semicolon.
+4. The default `toString` returns the name of the instance, here `"RED"`.
+5. Calls a method on a enum instance.
+6. Calls a method via enum class name.

examples/03_special_classes/03_Sealed Classes.md

@@ -1,19 +1,20 @@
 # Sealed Classes
 
+[Sealed classes](https://kotlinlang.org/docs/reference/sealed-classes.html) let you restrict the use of inheritance. Once you declare a class sealed, nobody else can create its subclasses.
+
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
 sealed class Mammal(val name: String)                                                   // 1
 
-class Cat(val catName: String) : Mammal(catName)
+class Cat(val catName: String) : Mammal(catName)                                        // 2
 class Human(val humanName: String, val job: String) : Mammal(humanName)
 
 fun greetMammal(mammal: Mammal): String {
-    when (mammal) {                                                                     // 2
-        is Human -> return "Hello ${mammal.name}; You're working as a ${mammal.job}"    // 3
-        is Cat -> return "Hello ${mammal.name}"                                         // 4
-                                                                                        // 5
-    }
+    when (mammal) {                                                                     // 3
+        is Human -> return "Hello ${mammal.name}; You're working as a ${mammal.job}"    // 4
+        is Cat -> return "Hello ${mammal.name}"                                         // 5     
+    }                                                                                   // 6
 }
 
 fun main() {
@@ -24,11 +25,11 @@ fun main() {
 </div>
 
 
-1. A sealed class is defined with two subclasses which must be in the same file
-2. The sealed class is used as an argument for a *when* expression 
-3. A smartcast is performed, casting Mammal to Human
-4. A smartcast is performed, casting Mammal to Cat
-5. The *else* clause is not necessary because all subclasses of the sealed class are covered.
-This is contrary to ordinary super classes, where an *else* would always be needed.
+1. Defines a sealed class. 
+2. Defines subclasses. Note that all subclasses must be in the same file.
+3. Uses an instance of the sealed class as an argument in a `when` expression. 
+4. A smartcast is performed, casting `Mammal` to `Human`.
+5. A smartcast is performed, casting `Mammal` to `Cat`.
+6. The `else`-case is not necessary here since all possible subclasses of the sealed class are covered. With a non-sealed superclass `else` would be required.
 
 

examples/03_special_classes/04_Object.md

@@ -1,21 +1,20 @@
-# Object keyword
+# Object Keyword
 
-First of all, let's start with some basic OOP concepts: a *class* is a blueprint, and an *object* is an instance of a class.
-You define a class, then create multiple instances of that class:
+Classes and objects in Kotlin work the same way as in most object-oriented languages: a *class* is a blueprint, and an *object* is an instance of a class. Usually, you define a class and then create multiple instances of that class:
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
 import java.util.Random
 
-class LuckDispatcher{                     //1 
+class LuckDispatcher {                    //1 
     fun getNumber() {                     //2 
         var objRandom = Random()
         println(objRandom.nextInt(90))
     }
 }
 
-fun main(){
+fun main() {
     val d1 = LuckDispatcher()             //3
     val d2 = LuckDispatcher()
 
@@ -26,24 +25,24 @@ fun main(){
 
 </div>
 
-1. blueprint definition
-2. method definition
-3. instance creation
-4. method calls 
+1. Defines a blueprint.
+2. Defines a method.
+3. Creates instances.
+4. Calls the method on instances. 
 
-Easy: we create two objects, both *instances* of LuckDispatcher class.
+In Kotlin you also have the [**object** keyword](https://kotlinlang.org/docs/reference/object-declarations.html). It is used to obtain a *data type with a single implementation*.
 
-In Kotlin you have also an **object** keyword. What is? is a *data type with a single implementation*.
+If you are a Java user and want to understand what "*single*" means, you can think of the **Singleton** pattern:
+it ensures you that only one instance of that class is created even if 2 threads try to create it.
 
-If you are a Java user and want to understand what "*single*" means, you can think to Singleton pattern:
-it allows you to check that one (and only one) instance of that class will be created, even if 2 threads access it.
+To achieve this in Kotlin, you only need to declare an `object`: no class, no constructor, only a lazy instance.
+Why lazy? Because it will be created once when the object is accessed. Otherwise, it won't even be created.
 
-To achieve that in Kotlin, you only need to declare an **object**: no class, no constructor, only a lazy instance.
-Why lazy? because it will be created one time, if object is used, otherwise, no.
+### `object` Expression
 
-In this example, you see a typical basic usage of an **object expression**: a simple object/properties structure.
-No need of class declaration: create a single object, declare members and access it. 
-Object like that, is often used like anonymous class in Java.
+Here is a basic typical usage of an `object` **expression**: a simple object/properties structure.
+There is no need to do so in class declaration: you create a single object, declare its members and access it within one function. 
+Objects like this are often created in Java as anonymous class instances.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -62,22 +61,22 @@ fun rentPrice(standardDays: Int, festivityDays: Int, specialDays: Int): Unit {
 
 }
 
-
-fun main(){
+fun main() {
     rentPrice(10, 2, 1)                                                         //5
 }
 ```
 
 </div>
 
-1. Create a rentPrice function, w/ parameters (regular days, festivity days, special days)
-2. Create rates object, where you set vars values
-3. Access object's vars
-4. Print total
-5. Access the instance (initialization), calling fun
+1. Creates a function with parameters.
+2. Creates an object to use when calculating the result value.
+3. Accesses the object's properties.
+4. Prints the result.
+5. Calls the function. This is when the object is actually created.
 
+### `object` Declaration
 
-You can have also **object declaration**: is not an expression, and cannot be used in a variable assignment, must be used directly:
+You can also use the `object` **declaration**. It isn't an expression, and can't be used in a variable assignment. You should use it to directly access its members:
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -88,7 +87,6 @@ object DoAuth {                                                 //1
     }
 }
 
-
 fun main(){
     DoAuth.takeParams("foo", "qwerty")                          //3
 }
@@ -97,39 +95,37 @@ fun main(){
 
 </div>
 
-1. create object declaration
-2. define method
-3. use the object (initialization), calling method
+1. Creates an object declaration.
+2. Defines the object method.
+3. Calls the method. This is when the object is actually created.
 
+### Companion Objects
 
-
-
-An object declaration, inside a class, defines another useful case: the **companion object**. 
-Syntactically similar to the static methods in Java, you call object's members using the *class* as qualifier.
-In Kotlin, before defining a companion object, decide whether it is better to write a simple *package-level* function.  
+An object declaration inside a class defines another useful case: the **companion object**. 
+Syntactically it's similar to the static methods in Java: you call object members using its *class name* as a qualifier.
+If you plan to use a companion object in Kotlin, consider using a *package-level* function instead.  
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
 class BigBen {                                  //1 
-    companion object Bonger{                    //2
-        fun getBongs(nTimes: Int){              //3
-            for (i in 1 .. nTimes){
+    companion object Bonger {                   //2
+        fun getBongs(nTimes: Int) {             //3
+            for (i in 1 .. nTimes) {
                 print("BONG ")
             }
         }
     }
 }
 
-
-fun main(){
+fun main() {
     BigBen.getBongs(12)                         //4
 }
 ```
 
 </div>
 
-1. class definition, companion initialization
-2. companion definition - name can be omitted
-3. method definition
-4. accessing companion object
+1. Defines a class.
+2. Defines a companion. Its name can be omitted.
+3. Defines a companion object method.
+4. Calls the companion object method via the class name.