Merge pull request Kotlin#49 from p7nov/productivity-revised

docs: revised Productivity Boosters

Author: AlexanderPrendota

examples/06_productivity_boosters/00_description.md

@@ -1,2 +1,2 @@
-# Productivity boosters
+# Productivity Boosters
 

examples/06_productivity_boosters/01_namedArguments.md

@@ -1,5 +1,7 @@
 # Named Arguments
 
+As with most other programming languages (Java, C++, etc.), Kotlin supports passing arguments to methods and constructors according to the order they are defined.
+Kotlin also supports [named arguments](https://kotlinlang.org/docs/reference/functions.html#named-arguments) to allow clearer invocations and avoid mistakes with the order of arguments. Such mistakes are hard to find because they are not detected by the compiler, for example, when two sequential arguments have the same type.
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
@@ -8,19 +10,16 @@ fun format(userName: String, domain: String) = "$userName@$domain"
 fun main() {
 //sampleStart
     println(format("mario", "example.com"))                         // 1
-    println(format(userName = "foo", domain = "bar.com"))           // 2
-    println(format(domain = "frog.com", userName = "pepe"))         // 3
+    println(format("domain.com", "username"))                       // 2
+    println(format(userName = "foo", domain = "bar.com"))           // 3
+    println(format(domain = "frog.com", userName = "pepe"))         // 4
 //sampleEnd
 }
 ```
 
 </div>
 
-1. As most of programming languages(Java, C++ etc), Kotlin supports passing arguments to methods and constructors
-    according to their order of definition.
-2. Kotlin also supports named arguments to allow clearer invocations and avoid
-    mistakes that otherwise would not be detected by the compiler (e.g.
-    switching the correct order of the arguments and constructing an email in
-    the form _gmail.com@username_).
-3. When invoking a method or constructor, named arguments do not have to
-    respect the original order of definition.
+1. Calls a function with argument values.
+2. Calls a function with switched arguments. No syntax errors, but the result _domain.com@username_ is incorrect.
+3. Calls a function with named arguments.   
+4. When invoking a function with named arguments, you can specify them in any order you like.

examples/06_productivity_boosters/02_String Templates.md

@@ -1,5 +1,6 @@
 # String Templates
 
+[String templates](https://kotlinlang.org/docs/reference/basic-types.html#string-templates) allow you to include variable references and expressions into strings. When the value of a string is requested (for example, by `println`), all references and expressions are substituted with actual values.
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
@@ -15,6 +16,6 @@ fun main() {
 
 </div>
 
-1. *Strings* in Kotlin can include references to variables that are interpolated
-2. In addition to simple variable references, they can also include any expression enclosed in curly braces.
+1. Prints a string with a variable reference. References in strings start with `$`.
+2. Prints a string with an expression. Expressions start with `$` and are enclosed in curly braces.
 

examples/06_productivity_boosters/03_Destructuring Declarations.md

@@ -1,6 +1,6 @@
 # Destructuring Declarations
 
-_Destructuring declaration_ syntax can be very handy and save you few lines of code.
+[Destructuring declaration](https://kotlinlang.org/docs/reference/multi-declarations.html#destructuring-declarations) syntax can be very handy, especially when you need an instance only for accessing its members. It lets you define the instance without a specific name therefore saving a few lines of code.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -27,9 +27,9 @@ fun main() {
 
 </div>
 
-1. Create a component on the left-hand side to match the arity of the right hand
-2. It can be used to iterate through maps. _name_ and _age_ variables are mapped to key and value now
-3. You can destructure built-in Pairs and Triples, even as return values from functions
+1. Destructures an `Array`. The number of variables on the left side matches the number of arguments on the right side.
+2. Maps can be destructured as well. `name` and `age` variables are mapped to the map key and value.
+3. Built-in `Pair` and `Triple` types support destructuring too, even as return values from functions.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -50,10 +50,10 @@ fun main() {
 
 </div>
 
-1. Define a data class that will be destructured later
-2. Values mapped to object fields
-3. Data class automatically defines the `component1()`, `component2()` corresponding methods, which will be called during destructuring
-4. Use _underscore_ if you don't need one of the values, avoiding the compiler hint indicating unused variable    
+1. Defines a data class.
+2. Destructures an instance. Declared values are mapped to the instance fields.
+3. Data class automatically defines the `component1()` and `component2()` methods that will be called during destructuring.
+4. Use _underscore_ if you don't need one of the values, avoiding the compiler hint indicating an unused variable.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -77,5 +77,5 @@ fun main() {
 
 </div>
 
-1. Define a custom `Pair` class with `component1()` and `component2()` methods
-2. Destructure instances of this class same as built-in `Pair`
+1. Defines a custom `Pair` class with `component1()` and `component2()` methods.
+2. Destructures an instance of this class the same way as for built-in `Pair`.

examples/06_productivity_boosters/04_Smart Casts.md

@@ -1,9 +1,9 @@
 # Smart Casts 
 
 
-The Kotlin compiler is smart enough to perform type casts automatically in most cases, including
-1. Casts from nullable types to their non-nullable counterparts
-2. Casts from a supertype to a subtype
+The Kotlin compiler is smart enough to perform type casts automatically in most cases, including:
+1. Casts from nullable types to their non-nullable counterparts.
+2. Casts from a supertype to a subtype.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -38,11 +38,10 @@ fun main() {
 
 </div>
 
+1. Declares a nullable variable.
+2. Smart-cast to non-nullable (thus allowing direct access to `isLeapYear`).
+3. Smart-cast inside a condition (this is possible because, like Java, Kotlin uses [short-circuiting](https://en.wikipedia.org/wiki/Short-circuit_evaluation)).
+4. Smart-cast inside acondition (also enabled by short-circuiting).
+5. Smart-cast to the subtype `LocalDate`.
 
-1. Declares a nullable variable
-2. Smart-cast to non-nullable (thus allowing direct access to `isLeapYear`)
-3. Smart-cast inside condition (this is possible because, like Java, Kotlin uses [short-circuiting](https://en.wikipedia.org/wiki/Short-circuit_evaluation))
-4. Smart-cast inside condition (also enabled by short-circuiting)
-5. Smart-cast to subtype LocalDate
-
-This way, you can automatically use variables as desired most of the time without doing obvious casts manually.
+This way, you can automatically use variables as desired in most cases without doing obvious casts manually.