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

Author: iliakan

Diff for: 1-js/02-first-steps/04-variables/article.md

@@ -290,7 +290,7 @@ In other words, capital-named constants are only used as aliases for "hard-coded
 
 Talking about variables, there's one more extremely important thing.
 
-A variable name should have a clean, obvious meaning, describe the data that it stores.
+A variable name should have a clean, obvious meaning, describing the data that it stores.
 
 Variable naming is one of the most important and complex skills in programming. A quick glance at variable names can reveal which code was written by a beginner versus an experienced developer.
 

Diff for: 1-js/04-object-basics/06-constructor-new/article.md

@@ -136,7 +136,7 @@ Usually, constructors do not have a `return` statement. Their task is to write a
 
 But if there is a `return` statement, then the rule is simple:
 
-- If `return` is called with object, then it is returned instead of `this`.
+- If `return` is called with an object, then the object is returned instead of `this`.
 - If `return` is called with a primitive, it's ignored.
 
 In other words, `return` with an object returns that object, in all other cases `this` is returned.

Diff for: 1-js/07-object-properties/02-property-accessors/article.md

@@ -102,9 +102,9 @@ There's no similar method to handle deletion of an accessor property. Only gette
 
 ## Accessor descriptors
 
-Descriptors for accessor properties are different -- as compared with data properties.
+Descriptors for accessor properties are different from those for data properties.
 
-For accessor properties, there is no `value` and `writable`, but instead there are `get` and `set` functions.
+For accessor properties, there is no `value` or `writable`, but instead there are `get` and `set` functions.
 
 That is, an accessor descriptor may have:
 

Diff for: 1-js/08-prototypes/03-native-prototypes/article.md

@@ -129,7 +129,7 @@ So, generally, modifying a native prototype is considered a bad idea.
 
 **In modern programming, there is only one case where modifying native prototypes is approved. That's polyfilling.**
 
-Polyfilling is a term for making a substitute for a method that exists in JavaScript specification, but not yet supported by current JavaScript engine.
+Polyfilling is a term for making a substitute for a method that exists in JavaScript specification, but is not yet supported by current JavaScript engine.
 
 Then we may implement it manually and populate the built-in prototype with it.
 

Diff for: 1-js/08-prototypes/04-prototype-methods/article.md

@@ -72,8 +72,8 @@ Why so?
 That's for historical reasons.
 
 - The `"prototype"` property of a constructor function works since very ancient times.
-- Later in the year 2012: `Object.create` appeared in the standard. It allowed to create objects with the given prototype, but did not allow to get/set it. So browsers implemented non-standard `__proto__` accessor that allowed to get/set a prototype at any time.
-- Later in the year 2015: `Object.setPrototypeOf` and `Object.getPrototypeOf` were added to the standard, to perform the same functionality as `__proto__`. As `__proto__` was de-facto implemented everywhere, it was kind-of deprecated and made its way to the Annex B of the standard, that is optional for non-browser environments.
+- Later, in the year 2012: `Object.create` appeared in the standard. It allowed to create objects with the given prototype, but did not allow to get/set it. So browsers implemented non-standard `__proto__` accessor that allowed to get/set a prototype at any time.
+- Later, in the year 2015: `Object.setPrototypeOf` and `Object.getPrototypeOf` were added to the standard, to perform the same functionality as `__proto__`. As `__proto__` was de-facto implemented everywhere, it was kind-of deprecated and made its way to the Annex B of the standard, that is optional for non-browser environments.
 
 As of now we have all these ways at our disposal.
 
@@ -82,7 +82,7 @@ Why was `__proto__` replaced by the functions `getPrototypeOf/setPrototypeOf`? T
 ```warn header="Don't change `[[Prototype]]` on existing objects if speed matters"
 Technically, we can get/set `[[Prototype]]` at any time. But usually we only set it once at the object creation time, and then do not modify: `rabbit` inherits from `animal`, and that is not going to change.
 
-And JavaScript engines are highly optimized to that. Changing a prototype "on-the-fly" with `Object.setPrototypeOf` or `obj.__proto__=` is a very slow operation, it breaks internal optimizations for object property access operations. So evade it unless you know what you're doing, or JavaScript speed totally doesn't matter for you.
+And JavaScript engines are highly optimized for this. Changing a prototype "on-the-fly" with `Object.setPrototypeOf` or `obj.__proto__=` is a very slow operation, it breaks internal optimizations for object property access operations. So avoid it unless you know what you're doing, or JavaScript speed totally doesn't matter for you.
 ```
 
 ## "Very plain" objects [#very-plain]
@@ -108,17 +108,17 @@ That shouldn't surprise us. The `__proto__` property is special: it must be eith
 
 But we didn't *intend* to implement such behavior, right? We want to store key/value pairs, and the key named `"__proto__"` was not properly saved. So that's a bug!
 
-Here the consequences are not terrible. But in other cases, we may be assigning object values, then the prototype may indeed be changed. As the result, the execution will go wrong in totally unexpected ways.
+Here the consequences are not terrible. But in other cases we may be assigning object values, and then the prototype may indeed be changed. As the result, the execution will go wrong in totally unexpected ways.
 
-What's worst -- usually developers do not think about such possibility at all. That makes such bugs hard to notice and even turn them into vulnerabilities, especially when JavaScript is used on server-side.
+What's worse -- usually developers do not think about such possibility at all. That makes such bugs hard to notice and even turn them into vulnerabilities, especially when JavaScript is used on server-side.
 
-Unexpected things also may happen when assigning to `toString` -- that's a function by default, and other built-in methods.
+Unexpected things also may happen when assigning to `toString`, which is a function by default, and to other built-in methods.
 
-How to evade the problem?
+How to avoid the problem?
 
 First, we can just switch to using `Map`, then everything's fine.
 
-But `Object` also can serve us well here, because language creators gave a thought to that problem long ago.
+But `Object` also can serve us well here, because language creators gave thought to that problem long ago.
 
 The `__proto__` is not a property of an object, but an accessor property of `Object.prototype`:
 

Diff for: 1-js/09-classes/01-class/article.md

@@ -231,7 +231,7 @@ new User().sayHi(); // Hello
 
 ## Getters/setters, other shorthands
 
-Just like literal objects, classes may include getters/setters, generators, computed properties etc.
+Just like literal objects, classes may include getters/setters, computed properties etc.
 
 Here's an example for `user.name` implemented using `get/set`:
 
@@ -298,8 +298,6 @@ class User {
 new User().sayHi();
 ```
 
-For a generator method, similarly, prepend it with `*`.
-
 ## Class properties
 
 ```warn header="Old browsers may need a polyfill"

Diff for: 1-js/09-classes/02-class-inheritance/3-class-extend-object/solution.md

@@ -26,7 +26,7 @@ Even after the fix, there's still important difference in `"class Rabbit extends
 As we know, the "extends" syntax sets up two prototypes:
 
 1. Between `"prototype"` of the constructor functions (for methods).
-2. Between the constructor functions itself (for static methods).
+2. Between the constructor functions themselves (for static methods).
 
 In our case, for `class Rabbit extends Object` it means:
 

Diff for: 1-js/09-classes/02-class-inheritance/article.md

@@ -259,7 +259,7 @@ The short answer is: constructors in inheriting classes must call `super(...)`,
 
 ...But why? What's going on here? Indeed, the requirement seems strange.
 
-Of course, there's an explanation. Let's get into details, so you'd really understand what's going on.
+Of course, there's an explanation. Let's get into details, so you'll really understand what's going on.
 
 In JavaScript, there's a distinction between a "constructor function of an inheriting class" and all others. In an inheriting class, the corresponding constructor function is labelled with a special internal property `[[ConstructorKind]]:"derived"`.
 

Diff for: 1-js/09-classes/04-private-protected-properties-methods/article.md

@@ -248,7 +248,7 @@ Unlike protected ones, private fields are enforced by the language itself. That'
 But if we inherit from `CoffeeMachine`, then we'll have no direct access to `#waterAmount`. We'll need to rely on `waterAmount` getter/setter:
 
 ```js
-class MegaCoffeeMachine extends CoffeeMachine() {
+class MegaCoffeeMachine extends CoffeeMachine {
   method() {
 *!*
     alert( this.#waterAmount ); // Error: can only access from CoffeeMachine

Diff for: 1-js/11-async/02-promise-basics/article.md

@@ -267,7 +267,7 @@ It's not exactly an alias of `then(f,f)` though. There are several important dif
 If a promise is pending, `.then/catch/finally` handlers wait for it. Otherwise, if a promise has already settled, they execute immediately:
 
 ```js run
-// an immediately resolved promise
+// the promise becomes resolved immediately upon creation
 let promise = new Promise(resolve => resolve("done!"));
 
 promise.then(alert); // done! (shows up right now)

Diff for: 1-js/12-generators-iterators/2-async-iterators-generators/article.md

@@ -21,7 +21,7 @@ let range = {
   [Symbol.iterator]() {
 */!*
     // ...it returns the iterator object:
-    // onward, for await..of works only with that object,
+    // onward, for..of works only with that object,
     // asking it for next values using next()
     return {
       current: this.from,
@@ -345,20 +345,18 @@ When we expect the data to come asynchronously, with delays, their async counter
 
 Syntax differences between async and regular iterators:
 
-|       | Iterators | Async iterators |
+|       | Iterable | Async Iterable |
 |-------|-----------|-----------------|
-| Object method to provide iterator | `Symbol.iterator` | `Symbol.asyncIterator` |
-| `next()` return value is              | any value         | `Promise`  |
+| Method to provide iterator | `Symbol.iterator` | `Symbol.asyncIterator` |
+| `next()` return value is          | `{value:…, done: true/false}`         | `Promise` that resolves to `{value:…, done: true/false}`  |
 
 Syntax differences between async and regular generators:
 
 |       | Generators | Async generators |
 |-------|-----------|-----------------|
 | Declaration | `function*` | `async function*` |
-| `generator.next()` returns              | `{value:…, done: true/false}`         | `Promise` that resolves to `{value:…, done: true/false}`  |
+| `next()` return value is          | `{value:…, done: true/false}`         | `Promise` that resolves to `{value:…, done: true/false}`  |
 
 In web-development we often meet streams of data, when it flows chunk-by-chunk. For instance, downloading or uploading a big file.
 
-We can use async generators to process such data, but it's also worth to mention that there's also another API called Streams, that provides special interfaces to work with such streams, to transform the data and to pass it from one stream to another (e.g. download from one place and immediately send elsewhere).
-
-Streams API is not a part of JavaScript language standard.
+We can use async generators to process such data. It's also noteworthy that in some environments, such as browsers, there's also another API called Streams, that provides special interfaces to work with such streams, to transform the data and to pass it from one stream to another (e.g. download from one place and immediately send elsewhere).

Diff for: 1-js/13-modules/02-import-export/article.md

@@ -151,7 +151,7 @@ say.*!*hi*/!*('John'); // Hello, John!
 say.*!*bye*/!*('John'); // Bye, John!
 ```
 
-## export default
+## Export default
 
 In practice, there are mainly two kinds of modules.
 
@@ -305,7 +305,7 @@ import func from '/path/to/func.js';
 ...
 ```
 
-Still, some teams consider it a serous drawback of default exports. So they prefer to always use named exports. Even if only a single thing is exported, it's still exported under a name, without `default`.
+Still, some teams consider it a serious drawback of default exports. So they prefer to always use named exports. Even if only a single thing is exported, it's still exported under a name, without `default`.
 
 That also makes re-export (see below) a little bit easier.
 

Diff for: 1-js/13-modules/03-modules-dynamic-imports/article.md

@@ -94,5 +94,5 @@ Dynamic imports work in regular scripts, they don't require `script type="module
 ```smart
 Although `import()` looks like a function call, it's a special syntax that just happens to use parentheses (similar to `super()`).
 
-So we can't copy `import` to a variable or use `.call/apply` with it. That's not a function.
+So we can't copy `import` to a variable or use `call/apply` with it. That's not a function.
 ```