Merge branch 'master' of github.com:javascript-tutorial/en.javascript.info into sync-468e3552

Author: iliakan

1-js/01-getting-started/1-intro/article.md

@@ -111,6 +111,7 @@ Examples of such languages:
 - [Flow](http://flow.org/) also adds data typing, but in a different way. Developed by Facebook.
 - [Dart](https://www.dartlang.org/) is a standalone language that has its own engine that runs in non-browser environments (like mobile apps), but also can be transpiled to JavaScript. Developed by Google.
 - [Brython](https://brython.info/) is a Python transpiler to JavaScript that enables the writing of applications in pure Python without JavaScript.
+- [Kotlin](https://kotlinlang.org/docs/reference/js-overview.html) is a modern, concise and safe programming language that can target the browser or Node.
 
 There are more. Of course, even if we use one of transpiled languages, we should also know JavaScript to really understand what we're doing.
 

1-js/02-first-steps/08-operators/article.md

@@ -219,7 +219,7 @@ alert( x ); // 5
 
 The fact of `=` being an operator, not a "magical" language construct has an interesting implication.
 
-Most operators in JavaScript return a value. That's obvious for `+` and `-`, but also true for `=`.
+All operators in JavaScript return a value. That's obvious for `+` and `-`, but also true for `=`.
 
 The call `x = value` writes the `value` into `x` *and then returns it*.
 

1-js/02-first-steps/18-javascript-specials/article.md

@@ -273,7 +273,7 @@ We covered three ways to create a function in JavaScript:
     ```
 
 
-- Functions may have local variables: those declared inside its body. Such variables are only visible inside the function.
+- Functions may have local variables: those declared inside its body or its parameter list. Such variables are only visible inside the function.
 - Parameters can have default values: `function sum(a = 1, b = 2) {...}`.
 - Functions always return something. If there's no `return` statement, then the result is `undefined`.
 

1-js/03-code-quality/01-debugging-chrome/article.md

@@ -135,7 +135,7 @@ There are buttons for it at the top of the right panel. Let's engage them.
     Clicking this again and again will step through all script statements one by one.
 
 <span class="devtools" style="background-position:-62px -192px"></span> -- "Step over": run the next command, but *don't go into a function*, hotkey `key:F10`.
-: Similar to the previous the "Step" command, but behaves differently if the next statement is a function call. That is: not a built-in, like `alert`, but a function of our own.
+: Similar to the previous "Step" command, but behaves differently if the next statement is a function call. That is: not a built-in, like `alert`, but a function of our own.
 
     The "Step" command goes into it and pauses the execution at its first line, while "Step over" executes the nested function call invisibly, skipping the function internals.
 

1-js/04-object-basics/07-optional-chaining/article.md

@@ -219,4 +219,4 @@ As we can see, all of them are straightforward and simple to use. The `?.` check
 
 A chain of `?.` allows to safely access nested properties.
 
-Still, we should apply `?.` carefully, only where it's acceptable that the left part doesn't to exist. So that it won't hide programming errors from us, if they occur.
+Still, we should apply `?.` carefully, only where it's acceptable that the left part doesn't exist. So that it won't hide programming errors from us, if they occur.

1-js/05-data-types/02-number/article.md

@@ -383,7 +383,7 @@ JavaScript has a built-in [Math](https://developer.mozilla.org/en/docs/Web/JavaS
 A few examples:
 
 `Math.random()`
-: Returns a random number from 0 to 1 (not including 1)
+: Returns a random number from 0 to 1 (not including 1).
 
     ```js run
     alert( Math.random() ); // 0.1234567894322
@@ -400,7 +400,7 @@ A few examples:
     ```
 
 `Math.pow(n, power)`
-: Returns `n` raised the given power
+: Returns `n` raised to the given power.
 
     ```js run
     alert( Math.pow(2, 10) ); // 2 in power 10 = 1024

1-js/05-data-types/06-iterable/article.md

@@ -174,7 +174,7 @@ When we use JavaScript for practical tasks in a browser or any other environment
 
 For instance, strings are both iterable (`for..of` works on them) and array-like (they have numeric indexes and `length`).
 
-But an iterable may not be array-like. And vice versa an array-like may not be iterable.
+But an iterable may be not array-like. And vice versa an array-like may be not iterable.
 
 For example, the `range` in the example above is iterable, but not array-like, because it does not have indexed properties and `length`.
 

1-js/05-data-types/10-destructuring-assignment/article.md

@@ -2,19 +2,22 @@
 
 The two most used data structures in JavaScript are `Object` and `Array`.
 
-Objects allow us to create a single entity that stores data items by key, and arrays allow us to gather data items into an ordered collection.
+- Objects allow us to create a single entity that stores data items by key. 
+- Arrays allow us to gather data items into an ordered list.
 
-But when we pass those to a function, it may need not an object/array as a whole, but rather individual pieces.
+Although, when we pass those to a function, it may need not an object/array as a whole. It may need individual pieces.
 
-*Destructuring assignment* is a special syntax that allows us to "unpack" arrays or objects into a bunch of variables, as sometimes that's more convenient. Destructuring also works great with complex functions that have a lot of parameters, default values, and so on.
+*Destructuring assignment* is a special syntax that allows us to "unpack" arrays or objects into a bunch of variables, as sometimes that's more convenient. 
+
+Destructuring also works great with complex functions that have a lot of parameters, default values, and so on. Soon we'll see that.
 
 ## Array destructuring
 
-An example of how the array is destructured into variables:
+Here's an example of how an array is destructured into variables:
 
 ```js
 // we have an array with the name and surname
-let arr = ["Ilya", "Kantor"]
+let arr = ["John", "Smith"]
 
 *!*
 // destructuring assignment
@@ -23,18 +26,22 @@ let arr = ["Ilya", "Kantor"]
 let [firstName, surname] = arr;
 */!*
 
-alert(firstName); // Ilya
-alert(surname);  // Kantor
+alert(firstName); // John
+alert(surname);  // Smith
 ```
 
 Now we can work with variables instead of array members.
 
 It looks great when combined with `split` or other array-returning methods:
 
-```js
-let [firstName, surname] = "Ilya Kantor".split(' ');
+```js run
+let [firstName, surname] = "John Smith".split(' ');
+alert(firstName); // John
+alert(surname);  // Smith
 ```
 
+As you can see, the syntax is simple. There are several peculiar details though. Let's see more examples, to better understand it.
+
 ````smart header="\"Destructuring\" does not mean \"destructive\"."
 It's called "destructuring assignment," because it "destructurizes" by copying items into variables. But the array itself is not modified.
 
@@ -69,26 +76,25 @@ In the code above, the second element of the array is skipped, the third one is
 let [a, b, c] = "abc"; // ["a", "b", "c"]
 let [one, two, three] = new Set([1, 2, 3]);
 ```
-
+That works, because internally a destructuring assignment works by iterating over the right value. It's kind of syntax sugar for calling `for..of` over the value to the right of `=` and assigning the values.
 ````
 
 
 ````smart header="Assign to anything at the left-side"
-
 We can use any "assignables" at the left side.
 
 For instance, an object property:
 ```js run
 let user = {};
-[user.name, user.surname] = "Ilya Kantor".split(' ');
+[user.name, user.surname] = "John Smith".split(' ');
 
-alert(user.name); // Ilya
+alert(user.name); // John
+alert(user.surname); // Smith
 ```
 
 ````
 
 ````smart header="Looping with .entries()"
-
 In the previous chapter we saw the [Object.entries(obj)](mdn:js/Object/entries) method.
 
 We can use it with destructuring to loop over keys-and-values of an object:
@@ -107,62 +113,81 @@ for (let [key, value] of Object.entries(user)) {
 }
 ```
 
-...And the same for a map:
+The similar code for a `Map` is simpler, as it's iterable:
 
 ```js run
 let user = new Map();
 user.set("name", "John");
 user.set("age", "30");
 
 *!*
+// Map iterates as [key, value] pairs, very convenient for destructuring
 for (let [key, value] of user) {
 */!*
   alert(`${key}:${value}`); // name:John, then age:30
 }
 ```
 ````
 
-```smart header="Swap variables trick"
-A well-known trick for swapping values of two variables:
+````smart header="Swap variables trick"
+There's a well-known trick for swapping values of two variables using a destructuring assignment:
 
 ```js run
 let guest = "Jane";
 let admin = "Pete";
 
-// Swap values: make guest=Pete, admin=Jane
+// Let's swap the values: make guest=Pete, admin=Jane
+*!*
 [guest, admin] = [admin, guest];
+*/!*
 
 alert(`${guest} ${admin}`); // Pete Jane (successfully swapped!)
 ```
 
 Here we create a temporary array of two variables and immediately destructure it in swapped order.
 
 We can swap more than two variables this way.
-
+````
 
 ### The rest '...'
 
-If we want not just to get first values, but also to gather all that follows -- we can add one more parameter that gets "the rest" using three dots `"..."`:
+Usually, if the array is longer when the list at the left, the "extra" items are omitted.
+
+For example, here only two items are taken, and the rest is just ignored:
 
 ```js run
-let [name1, name2, *!*...rest*/!*] = ["Julius", "Caesar", *!*"Consul", "of the Roman Republic"*/!*];
+let [name1, name2] = ["Julius", "Caesar", "Consul", "of the Roman Republic"];
 
 alert(name1); // Julius
 alert(name2); // Caesar
+// Furher items aren't assigned anywhere
+```
+
+If we'd like also to gather all that follows -- we can add one more parameter that gets "the rest" using three dots `"..."`:
+
+```js run
+let [name1, name2, *!*...rest*/!*] = ["Julius", "Caesar", *!*"Consul", "of the Roman Republic"*/!*];
 
 *!*
-// Note that type of `rest` is Array.
+// rest is array of items, starting from the 3rd one
 alert(rest[0]); // Consul
 alert(rest[1]); // of the Roman Republic
 alert(rest.length); // 2
 */!*
 ```
 
-The value of `rest` is the array of the remaining array elements. We can use any other variable name in place of `rest`, just make sure it has three dots before it and goes last in the destructuring assignment.
+The value of `rest` is the array of the remaining array elements. 
+
+We can use any other variable name in place of `rest`, just make sure it has three dots before it and goes last in the destructuring assignment.
+
+```js run
+let [name1, name2, *!*...titles*/!*] = ["Julius", "Caesar", "Consul", "of the Roman Republic"];
+// now titles = ["Consul", "of the Roman Republic"]
+```
 
 ### Default values
 
-If there are fewer values in the array than variables in the assignment, there will be no error. Absent values are considered undefined:
+If the array is shorter than the list of variables at the left, there'll be no errors. Absent values are considered undefined:
 
 ```js run
 *!*
@@ -187,7 +212,7 @@ alert(surname); // Anonymous (default used)
 
 Default values can be more complex expressions or even function calls. They are evaluated only if the value is not provided.
 
-For instance, here we use the `prompt` function for two defaults. But it will run only for the missing one:
+For instance, here we use the `prompt` function for two defaults:
 
 ```js run
 // runs only prompt for surname
@@ -197,7 +222,7 @@ alert(name);    // Julius (from array)
 alert(surname); // whatever prompt gets
 ```
 
-
+Please note: the `prompt` will run only for the missing value (`surname`).
 
 ## Object destructuring
 
@@ -209,7 +234,7 @@ The basic syntax is:
 let {var1, var2} = {var1:…, var2:…}
 ```
 
-We have an existing object at the right side, that we want to split into variables. The left side contains a "pattern" for corresponding properties. In the simple case, that's a list of variable names in `{...}`.
+We should have an existing object at the right side, that we want to split into variables. The left side contains an object-like "pattern" for corresponding properties. In the simplest case, that's a list of variable names in `{...}`.
 
 For instance:
 
@@ -229,7 +254,9 @@ alert(width);  // 100
 alert(height); // 200
 ```
 
-Properties `options.title`, `options.width` and `options.height` are assigned to the corresponding variables. The order does not matter. This works too:
+Properties `options.title`, `options.width` and `options.height` are assigned to the corresponding variables. 
+
+The order does not matter. This works too:
 
 ```js
 // changed the order in let {...}
@@ -238,7 +265,7 @@ let {height, width, title} = { title: "Menu", height: 200, width: 100 }
 
 The pattern on the left side may be more complex and specify the mapping between properties and variables.
 
-If we want to assign a property to a variable with another name, for instance, `options.width` to go into the variable named `w`, then we can set it using a colon:
+If we want to assign a property to a variable with another name, for instance, make `options.width` go into the variable named `w`, then we can set the variable name using a colon:
 
 ```js run
 let options = {

1-js/06-advanced-functions/04-var/article.md

@@ -52,7 +52,7 @@ if (true) {
 }
 
 *!*
-alert(test); // Error: test is not defined
+alert(test); // ReferenceError: test is not defined
 */!*
 ```
 
@@ -82,7 +82,7 @@ function sayHi() {
 }
 
 sayHi();
-alert(phrase); // Error: phrase is not defined
+alert(phrase); // ReferenceError: phrase is not defined
 ```
 
 As we can see, `var` pierces through `if`, `for` or other code blocks. That's because a long time ago in JavaScript, blocks had no Lexical Environments, and `var` is a remnant of that.
@@ -231,7 +231,7 @@ The Function Expression is wrapped with parenthesis `(function {...})`, because
 
 ```js run
 // Tries to declare and immediately call a function
-function() { // <-- Error: Function statements require a function name
+function() { // <-- SyntaxError: Function statements require a function name
 
   var message = "Hello";
 

1-js/06-advanced-functions/10-bind/article.md

@@ -247,7 +247,7 @@ The call to `mul.bind(null, 2)` creates a new function `double` that passes call
 
 That's called [partial function application](https://en.wikipedia.org/wiki/Partial_application) -- we create a new function by fixing some parameters of the existing one.
 
-Please note that here we actually don't use `this` here. But `bind` requires it, so we must put in something like `null`.
+Please note that we actually don't use `this` here. But `bind` requires it, so we must put in something like `null`.
 
 The function `triple` in the code below triples the value: