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

Author: iliakan

1-js/02-first-steps/02-structure/article.md

@@ -94,7 +94,7 @@ But it should be two separate statements, not one. Such a merging in this case i
 
 We recommend putting semicolons between statements even if they are separated by newlines. This rule is widely adopted by the community. Let's note once again -- *it is possible* to leave out semicolons most of the time. But it's safer -- especially for a beginner -- to use them.
 
-## Comments
+## Comments [#code-comments]
 
 As time goes on, programs become more and more complex. It becomes necessary to add *comments* which describe what the code does and why.
 

1-js/04-object-basics/01-object/article.md

@@ -101,7 +101,9 @@ For multiword properties, the dot access doesn't work:
 user.likes birds = true
 ```
 
-That's because the dot requires the key to be a valid variable identifier. That is: no spaces and other limitations.
+JavaScript doesn't understand that. It thinks that we address `user.likes`, and then gives a syntax error when comes across unexpected `birds`.
+
+The dot requires the key to be a valid variable identifier. That implies: contains no spaces, doesn't start with a digit and doesn't include special characters (`$` и `_` are allowed).
 
 There's an alternative "square bracket notation" that works with any string:
 
@@ -203,43 +205,6 @@ Square brackets are much more powerful than the dot notation. They allow any pro
 
 So most of the time, when property names are known and simple, the dot is used. And if we need something more complex, then we switch to square brackets.
 
-
-
-````smart header="Reserved words are allowed as property names"
-A variable cannot have a name equal to one of language-reserved words like "for", "let", "return" etc.
-
-But for an object property, there's no such restriction. Any name is fine:
-
-```js run
-let obj = {
-  for: 1,
-  let: 2,
-  return: 3
-};
-
-alert( obj.for + obj.let + obj.return );  // 6
-```
-
-Basically, any name is allowed, but there's a special one: `"__proto__"` that gets special treatment for historical reasons. For instance, we can't set it to a non-object value:
-
-```js run
-let obj = {};
-obj.__proto__ = 5;
-alert(obj.__proto__); // [object Object], didn't work as intended
-```
-
-As we see from the code, the assignment to a primitive `5` is ignored.
-
-That can become a source of bugs and even vulnerabilities if we intend to store arbitrary key-value pairs in an object, and allow a visitor to specify the keys.
-
-In that case the visitor may choose `__proto__` as the key, and the assignment logic will be ruined (as shown above).
-
-There is a way to make objects treat `__proto__` as a regular property, which we'll cover later, but first we need to know more about objects.
-
-There's also another data structure [Map](info:map-set), that we'll learn in the chapter <info:map-set>, which supports arbitrary keys.
-````
-
-
 ## Property value shorthand
 
 In real code we often use existing variables as values for property names.
@@ -284,7 +249,63 @@ let user = {
 };
 ```
 
-## Existence check
+## Property names limitations
+
+Property names (keys) must be either strings or symbols (a special type for identifiers, to be covered later).
+
+Other types are automatically converted to strings.
+
+For instance, a number `0` becomes a string `"0"` when used as a property key:
+
+```js run
+let obj = {
+  0: "test" // same as "0": "test"
+};
+
+// both alerts access the same property (the number 0 is converted to string "0")
+alert( obj["0"] ); // test
+alert( obj[0] ); // test (same property)
+```
+
+**Reserved words are allowed as property names.**
+
+As we already know, a variable cannot have a name equal to one of language-reserved words like "for", "let", "return" etc.
+
+But for an object property, there's no such restriction. Any name is fine:
+
+```js run
+let obj = {
+  for: 1,
+  let: 2,
+  return: 3
+};
+
+alert( obj.for + obj.let + obj.return );  // 6
+```
+
+We can use any string as a key, but there's a special property named `__proto__` that gets special treatment for historical reasons.
+
+For instance, we can't set it to a non-object value:
+
+```js run
+let obj = {};
+obj.__proto__ = 5; // assign a number
+alert(obj.__proto__); // [object Object] - the value is an object, didn't work as intended
+```
+
+As we see from the code, the assignment to a primitive `5` is ignored.
+
+The nature of `__proto__` will be revealed in detail later in the chapter [](info:prototype-inheritance).
+
+As for now, it's important to know that such behavior of `__proto__` can become a source of bugs and even vulnerabilities if we intend to store user-provided keys in an object.
+
+The problem is that a visitor may choose `__proto__` as the key, and the assignment logic will be ruined (as shown above).
+
+Later we'll see workarounds for the problem:
+1. We'll see how to make an objects treat `__proto__` as a regular property in the chapter [](info:prototype-methods).
+2. There's also study another data structure [Map](info:map-set) in the chapter <info:map-set>, which supports arbitrary keys.
+
+## Property existance test, "in" operator
 
 A notable objects feature is that it's possible to access any property. There will be no error if the property doesn't exist! Accessing a non-existing property just returns `undefined`. It provides a very common way to test whether the property exists -- to get it and compare vs undefined:
 

1-js/04-object-basics/03-symbol/article.md

@@ -178,22 +178,6 @@ alert( clone[id] ); // 123
 
 There's no paradox here. That's by design. The idea is that when we clone an object or merge objects, we usually want *all* properties to be copied (including symbols like `id`).
 
-````smart header="Property keys of other types are coerced to strings"
-We can only use strings or symbols as keys in objects. Other types are converted to strings.
-
-For instance, a number `0` becomes a string `"0"` when used as a property key:
-
-```js run
-let obj = {
-  0: "test" // same as "0": "test"
-};
-
-// both alerts access the same property (the number 0 is converted to string "0")
-alert( obj["0"] ); // test
-alert( obj[0] ); // test (same property)
-```
-````
-
 ## Global symbols
 
 As we've seen, usually all symbols are different, even if they have the same name. But sometimes we want same-named symbols to be same entities. For instance, different parts of our application want to access symbol `"id"` meaning exactly the same property.

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

@@ -12,7 +12,7 @@ If an object isn't technically an array, but represents a collection (list, set)
 
 We can easily grasp the concept of iterables by making one of our own.
 
-For instance, we have an object, that is not an array, but looks suitable for `for..of`.
+For instance, we have an object that is not an array, but looks suitable for `for..of`.
 
 Like a `range` object that represents an interval of numbers:
 
@@ -294,7 +294,7 @@ Objects that can be used in `for..of` are called *iterable*.
 
 - Technically, iterables must implement the method named `Symbol.iterator`.
     - The result of `obj[Symbol.iterator]` is called an *iterator*. It handles the further iteration process.
-    - An iterator must have the method named `next()` that returns an object `{done: Boolean, value: any}`, here `done:true` denotes the iteration end, otherwise the `value` is the next value.
+    - An iterator must have the method named `next()` that returns an object `{done: Boolean, value: any}`, here `done:true` denotes the end of the iteration process, otherwise the `value` is the next value.
 - The `Symbol.iterator` method is called automatically by `for..of`, but we also can do it directly.
 - Built-in iterables like strings or arrays, also implement `Symbol.iterator`.
 - String iterator knows about surrogate pairs.

1-js/05-data-types/08-weakmap-weakset/article.md

@@ -141,7 +141,6 @@ And here's another part of the code, maybe another file using it:
 let john = { name: "John" };
 
 countUser(john); // count his visits
-countUser(john);
 
 // later john leaves us
 john = null;

1-js/08-prototypes/01-prototype-inheritance/article.md

@@ -16,7 +16,7 @@ The prototype is a little bit "magical". When we want to read a property from `o
 
 The property `[[Prototype]]` is internal and hidden, but there are many ways to set it.
 
-One of them is to use `__proto__`, like this:
+One of them is to use the special name `__proto__`, like this:
 
 ```js run
 let animal = {

1-js/10-error-handling/1-try-catch/article.md

@@ -4,7 +4,7 @@ No matter how great we are at programming, sometimes our scripts have errors. Th
 
 Usually, a script "dies" (immediately stops) in case of an error, printing it to console.
 
-But there's a syntax construct `try..catch` that allows to "catch" errors and, instead of dying, do something more reasonable.
+But there's a syntax construct `try..catch` that allows us to "catch" errors so the script can, instead of dying, do something more reasonable.
 
 ## The "try..catch" syntax
 
@@ -26,13 +26,13 @@ It works like this:
 
 1. First, the code in `try {...}` is executed.
 2. If there were no errors, then `catch(err)` is ignored: the execution reaches the end of `try` and goes on, skipping `catch`.
-3. If an error occurs, then `try` execution is stopped, and the control flows to the beginning of `catch(err)`. The `err` variable (can use any name for it) will contain an error object with details about what happened.
+3. If an error occurs, then the `try` execution is stopped, and control flows to the beginning of `catch(err)`. The `err` variable (we can use any name for it) will contain an error object with details about what happened.
 
 ![](try-catch-flow.svg)
 
-So, an error inside the `try {…}` block does not kill the script: we have a chance to handle it in `catch`.
+So, an error inside the `try {…}` block does not kill the script -- we have a chance to handle it in `catch`.
 
-Let's see examples.
+Let's look at some examples.
 
 - An errorless example: shows `alert` `(1)` and `(2)`:
 
@@ -87,7 +87,7 @@ try {
 
 The JavaScript engine first reads the code, and then runs it. The errors that occur on the reading phase are called "parse-time" errors and are unrecoverable (from inside that code). That's because the engine can't understand the code.
 
-So, `try..catch` can only handle errors that occur in the valid code. Such errors are called "runtime errors" or, sometimes, "exceptions".
+So, `try..catch` can only handle errors that occur in valid code. Such errors are called "runtime errors" or, sometimes, "exceptions".
 ````
 
 

1-js/11-async/03-promise-chaining/article.md

@@ -252,7 +252,7 @@ fetch('/article/promise-chaining/user.json')
   });
 ```
 
-There is also a method `response.json()` that reads the remote data and parses it as JSON. In our case that's even more convenient, so let's switch to it.
+The `response` object returned from `fetch` also includes the method `response.json()` that reads the remote data and parses it as JSON. In our case that's even more convenient, so let's switch to it.
 
 We'll also use arrow functions for brevity:
 

1-js/11-async/08-async-await/article.md

@@ -143,7 +143,7 @@ But we can wrap it into an anonymous async function, like this:
 
 ````
 ````smart header="`await` accepts \"thenables\""
-Like `promise.then`, `await` allows to use thenable objects (those with a callable `then` method). The idea is that a third-party object may not be a promise, but promise-compatible: if it supports `.then`, that's enough to use with `await`.
+Like `promise.then`, `await` allows us to use thenable objects (those with a callable `then` method). The idea is that a third-party object may not be a promise, but promise-compatible: if it supports `.then`, that's enough to use it with `await`.
 
 Here's a demo `Thenable` class; the `await` below accepts its instances:
 

1-js/12-generators-iterators/1-generators/article.md

@@ -102,7 +102,7 @@ But usually the first syntax is preferred, as the star `*` denotes that it's a g
 
 As you probably already guessed looking at the `next()` method, generators are [iterable](info:iterable).
 
-We can get loop over values by `for..of`:
+We can loop over their values using `for..of`:
 
 ```js run
 function* generateSequence() {
@@ -314,11 +314,11 @@ alert(str); // 0..9A..Za..z
 
 A generator composition is a natural way to insert a flow of one generator into another. It doesn't use extra memory to store intermediate results.
 
-## "yield" is a two-way road
+## "yield" is a two-way street
 
 Until this moment, generators were similar to iterable objects, with a special syntax to generate values. But in fact they are much more powerful and flexible.
 
-That's because `yield` is a two-way road: it not only returns the result outside, but also can pass the value inside the generator.
+That's because `yield` is a two-way street: it not only returns the result to the outside, but also can pass the value inside the generator.
 
 To do so, we should call `generator.next(arg)`, with an argument. That argument becomes the result of `yield`.