Wording adjusted

src/i_introduction/_4_String_Templates/StringTemplates.kt

@@ -13,8 +13,8 @@ fun foo3(c: Boolean, x: Int, y: Int) = "Any expression can be used: ${if (c) x e
 
 fun foo4() =
 """
-Triple quotes are used
-to contain raw strings.
+Triple quotes denote
+"raw" strings.
 """
 
 fun getPatternInAUsualString() = "(\\w)* (\\w)* \\((\\d{2})\\.(\\d{2})\\.(\\d{4})\\)"
@@ -27,8 +27,8 @@ val month = "(JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC)"
 
 fun todoTask4() = TODO(
         task = """Task4.
-        Rewrite 'getPatternInARawString' the way it matches 'Douglas Adams (11 MAR 1952)'.
-        Use 'month' variable.""",
+        Rewrite 'getPatternInARawString' so that it matches 'Douglas Adams (11 MAR 1952)'.
+        Use the 'month' variable.""",
         references = { getPatternInARawString(); month })
 
 fun task4(): String = todoTask4()

src/i_introduction/_5_Nullable_Types/NullableTypes.kt

@@ -55,7 +55,7 @@ fun fail() = throw Exception()
 fun todoTask5(client: Client?, message: String?, mailer: Mailer) = TODO(
         task = """Task5.
             Rewrite JavaCode5.sendMessageToClient to kotlin (using only one 'if').
-            Declarations of Client, PersonalInfo and Mailer are below.""",
+            Declarations of Client, PersonalInfo and Mailer are given below.""",
         references = { JavaCode5().sendMessageToClient(client, message, mailer) }
 )
 

src/i_introduction/_6_Smart_Casts/SmartCasts.kt

@@ -12,7 +12,7 @@ fun eval(e: Expr): Int {
         return n.value
     }
     if (e is Sum) {
-        // actually, there is no need to create a separate variable:
+        // actually, there is no need in a separate variable:
         return eval(e.left) + eval(e.right)
     }
     throw IllegalArgumentException("Unknown expression")

src/i_introduction/_7_Data_Classes/DataClasses.kt

@@ -15,7 +15,7 @@ fun useFromJava() {
     // property 'var mutable' = backing field + getter + setter
 }
 
-// It's the same as the following (redundant code is generated):
+// It's the same as the following (getters are generated by the default):
 class Person2(_name: String, _age: Int) { //_name, _age are constructor parameters
     val name: String = _name //property initialization is the part of constructor
       get() {
@@ -33,13 +33,13 @@ class Person2(_name: String, _age: Int) { //_name, _age are constructor paramete
 
 data class Person3(val name: String, val age: Int)
 
-// This class is the same only 42 lines shorter than Java class Person4. =)
+// This class is as good as Person4 (written in Java), 42 lines shorter. =)
 
 fun todoTask7() = TODO(
         task = """There is no task for you here.
-        Just confirm you're not forgetting to read carefully all code examples and comments and
-        ask questions if any. =)
-        More information about classes in kotlin can be found in syntax.classesObjectsTraits""",
+        Just make sure you're not forgetting to read carefully all code examples and comments and
+        ask questions if you have any. =)
+        More information about classes in kotlin can be found in syntax/classesObjectsTraits.kt""",
         references = { JavaCode7.Person4("???", -1) }
 )
 

src/i_introduction/_8_Extension_Functions/ExtensionFunctions.kt

@@ -9,7 +9,7 @@ fun String.lastChar() = this.charAt(this.length - 1)
 fun String.lastChar1() = charAt(length - 1)
 
 fun use() {
-    // it's visible in completion and can be easily found
+    // Try Ctrl+Space after the dot: lastChar() visible in completion and can be easily found
     "abc".lastChar()
 }
 
@@ -18,8 +18,8 @@ fun use() {
 
 fun todoTask8() = TODO(
         """Task8.
-        Implement extension functions Int.r, Pair<Int, Int>.r
-        to support the following way to create rational numbers:
+        Implement extension functions Int.r(), Pair<Int, Int>.r()
+        to support the following way of creating rational numbers:
         1.r(), Pair(1, 2).r()""",
         references = { 1.r(); Pair(1, 2).r(); RationalNumber(1, 9) })
 

src/i_introduction/_9_Extensions_On_Collections/ExtensionsOnCollections.kt

@@ -29,10 +29,10 @@ fun operationsWithMaps() {
     for ((key, value) in map) {
     }
 
-    //convenient way to address elements:
+    //convenient way to access elements:
     map[43] = map[42] + " plus one"
 
-    //the details (how it works) you'll found in 'Conventions' later
+    //the details (how it works) you'll found in 'Conventions' task later
 
     println(map)
 }

src/ii_conventions/_10_Comparison_.kt

@@ -4,7 +4,7 @@ import util.TODO
 
 fun compareStrings(s1: String?, s2: String?) {
     s1 == s2
-    // generates to
+    // is compiled to
     s1?.equals(s2) ?: s2.identityEquals(null)
 }
 
@@ -14,17 +14,18 @@ trait B {
 
 fun test(b1: B, b2: B) {
     b1 < b2
-    //generates to
+    // is compiled to
     b1.compareTo(b2) < 0
 
     b1 >= b2
-    //generates to
+    // is compiled to
     b1.compareTo(b2) >= 0
 }
 
 fun todoTask10() = TODO(
         task = """Task10.
-        Uncomment the commented line to make it compile. Add all changes to the file MyDate.kt.
+        Uncomment the commented line and make it compile.
+        Add all changes to the file MyDate.kt.
         Make class MyDate implement Comparable.""",
         references = { (date: MyDate) -> }
 )

src/ii_conventions/_11_ForLoop.kt

@@ -16,7 +16,7 @@ fun iterateOverString() {
 }
 
 fun iterateOverRange() {
-    //'..' resolves to 'rangeTo' function
+    //'..' resolves to the 'rangeTo' function
     val intRange = 1..10
     for (i in intRange) {}
     for (i in 1..10) {}
@@ -27,7 +27,7 @@ fun todoTask11() = TODO(
         task = """Task11.
         Uncomment the commented code and make it compile. Add all changes to the file MyDate.kt.
         Add a class DateRange and make it implement Iterable<MyDate>.
-        Use an util function MyDate.nextDay.""",
+        Use an utility function MyDate.nextDay.""",
         references = { (date: MyDate) -> date.nextDay() })
 
 

src/ii_conventions/_12_InRange.kt

@@ -8,7 +8,7 @@ trait Container<E> {
 
 fun inConvention(container: Container<String>) {
     "a" in container
-    //translated to
+    // compiles to
     container.contains("a")
 }
 
@@ -24,7 +24,7 @@ fun stringRange(s: String) {
 }
 
 fun todoTask12() = TODO("""Task12.
-        Uncomment the commented line to make it compile. Add all changes to the file MyDate.kt.
+        Uncomment the commented line and make it compile. Add all changes to the file MyDate.kt.
         Make class DateRange implement kotlin.Range."""
 )
 

src/ii_conventions/_13_OperatorsOverloading.kt

@@ -11,7 +11,7 @@ fun infixNotation() {
 }
 
 //Only predefined operators can be overloaded by the corresponding names
-//The whole list of operators can be found in syntax.OperatorOverloading
+//A complete list of operators can be found in syntax/OperatorOverloading.kt
 trait A {
     fun plus(a: A): A
     fun minus(a: A): A
@@ -26,10 +26,10 @@ fun use(a1: A, a2: A) {
 
 fun todoTask13() = TODO(
         task = """Task13.
-        Implement a kind of date arithmetic, let to add years, weeks and days to a date.
+        Implement a kind of date arithmetic, support adding years, weeks and days to a date.
         Use classes MyDate and TimeInterval. Add all the changes to the file MyDate.kt.
-        Use an util function MyDate.addTimeIntervals.
-        Uncomment the commented line and make it compiled.
+        Use a utility function MyDate.addTimeIntervals.
+        Uncomment the commented line and make it compile.
         You may need to add an extra class here.""",
         references = {(date: MyDate, timeInterval: TimeInterval) -> date.addTimeIntervals(timeInterval, 1) })
 

src/ii_conventions/_14_MultiAssignment.kt

@@ -37,14 +37,15 @@ fun howWorksMultiAssignmentInForCycle() {
     }
 }
 
-//with 'data' annotation 'component1', 'component2', etc. are generated for constructor parameters
+// with 'data' annotation 'component1', 'component2', etc. are generated automatically
+// for constructor parameters
 data class MyAnotherPair(val i: Int, val s: String)
 
-//that's why we can multi assign Date class:
+//that's why we can multi-assign Date class:
 fun multiAssignDate(date: MyDate) {
     val (year, month, dayOfMonth) = date
 }
 
-fun todoTask14() = TODO("Again no special task. Just tell if you are interested in Kotlin. =)")
+fun todoTask14() = TODO("Again no special task. Just tell us if you are interested in Kotlin. =)")
 
 fun task14(): Boolean = todoTask14()

src/ii_conventions/_15_Invoke_.kt

@@ -20,14 +20,14 @@ fun testFunctionType(f: (Int) -> Int) {
     f(1)
 }
 
-// click 'Ctrl + B' on round bracket to navigate to 'invoke'
+// Press 'Ctrl + B' on round bracket to navigate to 'invoke'
 
 // you can add invoke extension for any class,
-// but it's better not to be mad about it
+// but it's better not to overdo it
 fun Int.invoke() { println(this) }
 
 fun testTypeWithInvokeExtension() {
-    1() //wtf?..
+    1() //huh?..
 }
 
 class Invokable

src/iii_properties/_16_Properties_.kt

@@ -4,12 +4,12 @@ import java.util.Random
 import util.TODO
 
 fun localVariables() {
-    // immutable reference
+    // immutable variable
     val i = 1
     // doesn't compile:
     // i = 2
 
-    // mutable reference
+    // mutable variable
     var j = 3
     j = 1765
 }
@@ -20,7 +20,7 @@ class SimpleProperty {
 }
 
 fun usage(sp: SimpleProperty) {
-    //All usages are compiled to getter and setter invocations.
+    //Usages are compiled to getter and setter invocations.
     //You can open "View -> Tool windows -> Kotlin" and see the bytecode.
     val x = sp.property
     sp.property = x + 1

src/iii_properties/_17_DelegatesExamples.kt

@@ -26,8 +26,8 @@ class Commodity(data: MutableMap<String, Any?>) {
 
 fun <T> todoTask17(): ReadWriteProperty<Commodity, T> = TODO(
         task = """Task17.
-        Make the properties in class Commodity reflect the data storing in the map.
-        The value of property 'price' should be the value in 'data' by the key "price".
+        Make the properties in class Commodity reflect the data stored in the map.
+        E.g., the value of property 'price' should be the value in 'data' by the key "price".
         Use Delegates.mapVar""",
         references = {
             val data = hashMapOf<String, Any?>("description" to "snowboard", "price" to 349, "isAvailable" to true)