Sync with upstream @ 7b761858

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

@@ -56,17 +56,21 @@ alert( 8 % 3 ); // 2, a remainder of 8 divided by 3
 
 ### Exponentiation **
 
-The exponentiation operator `a ** b` multiplies `a` by itself `b` times.
+The exponentiation operator `a ** b` raises `a` to the power of `b`.
+
+In school maths, we write that as a<sup>b</sup>.
 
 For instance:
 
 ```js run
-alert( 2 ** 2 ); // 4  (2 multiplied by itself 2 times)
-alert( 2 ** 3 ); // 8  (2 * 2 * 2, 3 times)
-alert( 2 ** 4 ); // 16 (2 * 2 * 2 * 2, 4 times)
+alert( 2 ** 2 ); // 2² = 4  
+alert( 2 ** 3 ); // 2³ = 8 
+alert( 2 ** 4 ); // 2⁴ = 16
 ```
 
-Mathematically, the exponentiation is defined for non-integer numbers as well. For example, a square root is an exponentiation by `1/2`:
+Just like in maths, the exponentiation operator is defined for non-integer numbers as well. 
+
+For example, a square root is an exponentiation by ½:
 
 ```js run
 alert( 4 ** (1/2) ); // 2 (power of 1/2 is the same as a square root)

1-js/02-first-steps/13-while-for/article.md

@@ -368,9 +368,18 @@ break label; // jump to the label below (doesn't work)
 label: for (...)
 ```
 
-A call to `continue` is only possible from inside the loop.
+A `break` directive must be inside a code block. Technically, any labelled code block will do, e.g.:
+```js
+label: {
+  // ...
+  break label; // works
+  // ...
+}
+```
+
+...Although, 99.9% of the time `break` used is inside loops, as we've seen in the examples above.
 
-The `break` directive may be placed before code blocks too, as `label: { ... }`, but it's almost never used like that. And it also works only inside-out.
+A `continue` is only possible from inside a loop.
 ````
 
 ## Summary

1-js/02-first-steps/15-function-basics/2-rewrite-function-question-or/solution.md

@@ -14,4 +14,4 @@ function checkAge(age) {
 }
 ```
 
-Note that the parentheses around `age > 18` are not required here. They exist for better readabilty.
+Note that the parentheses around `age > 18` are not required here. They exist for better readability.

1-js/02-first-steps/17-arrow-functions-basics/1-rewrite-arrow/solution.md

@@ -1,7 +1,7 @@
 
 ```js run
 function ask(question, yes, no) {
-  if (confirm(question)) yes()
+  if (confirm(question)) yes();
   else no();
 }
 

1-js/02-first-steps/17-arrow-functions-basics/1-rewrite-arrow/task.md

@@ -5,7 +5,7 @@ Replace Function Expressions with arrow functions in the code below:
 
 ```js run
 function ask(question, yes, no) {
-  if (confirm(question)) yes()
+  if (confirm(question)) yes();
   else no();
 }
 

1-js/05-data-types/08-weakmap-weakset/01-recipients-read/solution.md

@@ -25,7 +25,7 @@ messages.shift();
 // now readMessages has 1 element (technically memory may be cleaned later)
 ```
 
-The `WeakSet` allows to store a set of messages and easily check for the existance of a message in it.
+The `WeakSet` allows to store a set of messages and easily check for the existence of a message in it.
 
 It cleans up itself automatically. The tradeoff is that we can't iterate over it,  can't get "all read messages" from it directly. But we can do it by iterating over all messages and filtering those that are in the set.
 

1-js/05-data-types/11-date/article.md

@@ -348,7 +348,7 @@ let time1 = 0;
 let time2 = 0;
 
 *!*
-// run bench(upperSlice) and bench(upperLoop) each 10 times alternating
+// run bench(diffSubtract) and bench(diffGetTime) each 10 times alternating
 for (let i = 0; i < 10; i++) {
   time1 += bench(diffSubtract);
   time2 += bench(diffGetTime);

1-js/06-advanced-functions/03-closure/10-make-army/solution.md

@@ -88,11 +88,11 @@ Let's examine what exactly happens inside `makeArmy`, and the solution will beco
 
     Here `let j = i` declares an "iteration-local" variable `j` and copies `i` into it. Primitives are copied "by value", so we actually get an independent copy of `i`, belonging to the current loop iteration.
 
-    The shooters work correctly, because the value of `i` now lives a little bit closer. Not in `makeArmy()` Lexical Environment, but in the Lexical Environment that corresponds the current loop iteration:
+    The shooters work correctly, because the value of `i` now lives a little bit closer. Not in `makeArmy()` Lexical Environment, but in the Lexical Environment that corresponds to the current loop iteration:
 
     ![](lexenv-makearmy-while-fixed.svg)
 
-    Such problem could also be avoided if we used `for` in the beginning, like this:
+    Such a problem could also be avoided if we used `for` in the beginning, like this:
 
     ```js run demo
     function makeArmy() {

1-js/06-advanced-functions/03-closure/7-let-scope/solution.md

@@ -27,7 +27,7 @@ The code above demonstrates it.
 function func() {
 *!*
   // the local variable x is known to the engine from the beginning of the function,
-  // but "unitialized" (unusable) until let ("dead zone")
+  // but "uninitialized" (unusable) until let ("dead zone")
   // hence the error
 */!*
 

1-js/06-advanced-functions/03-closure/article.md

@@ -146,7 +146,7 @@ Despite being simple, slightly modified variants of that code have practical use
 
 How does this work? If we create multiple counters, will they be independent? What's going on with the variables here?
 
-Undestanding such things is great for the overall knowledge of JavaScript and beneficial for more complex scenarios. So let's go a bit in-depth.
+Understanding such things is great for the overall knowledge of JavaScript and beneficial for more complex scenarios. So let's go a bit in-depth.
 
 ## Lexical Environment
 

1-js/06-advanced-functions/06-function-object/5-sum-many-brackets/solution.md

@@ -52,4 +52,4 @@ function f(b) {
 }
 ```
 
-This `f` will be used in the next call, again return itself, so many times as needed. Then, when used as a number or a string -- the `toString` returns the `currentSum`. We could also use `Symbol.toPrimitive` or `valueOf` here for the conversion.
+This `f` will be used in the next call, again return itself, as many times as needed. Then, when used as a number or a string -- the `toString` returns the `currentSum`. We could also use `Symbol.toPrimitive` or `valueOf` here for the conversion.

1-js/06-advanced-functions/09-call-apply-decorators/04-throttle/solution.md

@@ -12,11 +12,10 @@ function throttle(func, ms) {
       savedThis = this;
       return;
     }
+    isThrottled = true;
 
     func.apply(this, arguments); // (1)
 
-    isThrottled = true;
-
     setTimeout(function() {
       isThrottled = false; // (3)
       if (savedArgs) {

1-js/09-classes/01-class/article.md

@@ -25,7 +25,7 @@ class MyClass {
 }
 ```
 
-Then `new MyClass()` creates a new object with all the listed methods.
+Then use `new MyClass()` to create a new object with all the listed methods.
 
 The `constructor()` method is called automatically by `new`, so we can initialize the object there.
 
@@ -53,7 +53,7 @@ When `new User("John")` is called:
 1. A new object is created.
 2. The `constructor` runs with the given argument and assigns it to `this.name`.
 
-...Then we can call methods, such as `user.sayHi`.
+...Then we can call object methods, such as `user.sayHi()`.
 
 
 ```warn header="No comma between class methods"
@@ -64,7 +64,7 @@ The notation here is not to be confused with object literals. Within the class,
 
 ## What is a class?
 
-So, what exactly is a `class`? That's not an entirely  new language-level entity, as one might think.
+So, what exactly is a `class`? That's not an entirely new language-level entity, as one might think.
 
 Let's unveil any magic and see what a class really is. That'll help in understanding many complex aspects.
 
@@ -85,11 +85,9 @@ alert(typeof User); // function
 ```
 
 What `class User {...}` construct really does is:
-1. Creates a function named `User`, that becomes the result of the class declaration.
-    - The function code is taken from the `constructor` method (assumed empty if we don't write such method).
-3. Stores all methods, such as `sayHi`, in `User.prototype`.
 
-Afterwards, for new objects, when we call a method, it's taken from the prototype, just as  described in the chapter <info:function-prototype>. So `new User` object has access to class methods.
+1. Creates a function named `User`, that becomes the result of the class declaration. The function code is taken from the `constructor` method (assumed empty if we don't write such method).
+2. Stores class methods, such as `sayHi`, in `User.prototype`.
 
 After `new User` object is created, when we call its method, it's taken from the prototype, just as described in the chapter <info:function-prototype>. So the object has access to class methods.
 
@@ -99,7 +97,6 @@ We can illustrate the result of `class User` declaration as:
 
 Here's the code to introspect it:
 
-
 ```js run
 class User {
   constructor(name) { this.name = name; }
@@ -113,7 +110,7 @@ alert(typeof User); // function
 alert(User === User.prototype.constructor); // true
 
 // The methods are in User.prototype, e.g:
-alert(User.prototype.sayHi); // alert(this.name);
+alert(User.prototype.sayHi); // the code of the sayHi method
 
 // there are exactly two methods in the prototype
 alert(Object.getOwnPropertyNames(User.prototype)); // constructor, sayHi
@@ -171,16 +168,15 @@ Still, there are important differences.
     ```
     There are other differences, we'll see them soon.
 
-2. Class methods are non-enumerable
+2. Class methods are non-enumerable.
     A class definition sets `enumerable` flag to `false` for all methods in the `"prototype"`.
 
     That's good, because if we `for..in` over an object, we usually don't want its class methods.
 
-3. Classes always `use strict`
+3. Classes always `use strict`.
     All code inside the class construct is automatically in strict mode.
 
-
-Also, in addition to its basic operation, the `class` syntax brings many other features with it which we'll explore later.
+Besides, `class` syntax brings many other features that we'll explore later.
 
 ## Class Expression
 
@@ -196,21 +192,22 @@ let User = class {
 };
 ```
 
-Similar to Named Function Expressions, class expressions may or may not have a name.
+Similar to Named Function Expressions, class expressions may have a name.
 
 If a class expression has a name, it's visible inside the class only:
 
 ```js run
-// "Named Class Expression" (alas, no such term, but that's what's going on)
+// "Named Class Expression"
+// (no such term in the spec, but that's similar to Named Function Expression)
 let User = class *!*MyClass*/!* {
   sayHi() {
-    alert(MyClass); // MyClass is visible only inside the class
+    alert(MyClass); // MyClass name is visible only inside the class
   }
 };
 
 new User().sayHi(); // works, shows MyClass definition
 
-alert(MyClass); // error, MyClass not visible outside of the class
+alert(MyClass); // error, MyClass name isn't visible outside of the class
 ```
 
 We can even make classes dynamically "on-demand", like this:
@@ -243,7 +240,7 @@ class User {
 
   constructor(name) {
     // invokes the setter
-    this._name = name;
+    this.name = name;
   }
 
 *!*
@@ -277,10 +274,11 @@ Technically, such class declaration works by creating getters and setters in `Us
 Here's an example with a computed method name using brackets `[...]`:
 
 ```js run
-function f() { return "sayHi"; }
-
 class User {
-  [f()]() {
+
+*!*
+  ['say' + 'Hi']() {
+*/!*
     alert("Hello");
   }
 
@@ -405,29 +403,11 @@ That's especially useful in browser environment, for event listeners.
 
 ## Summary
 
-JavaScript provides many ways to create a class.
-
-First, as per the general object-oriented terminology, a class is something that provides "object templates", allows to create same-structured objects.
-
-When we say "a class", that doesn't necessary means the `class` keyword.
-
-This is a class:
-
-```js
-function User(name) {
-  this.sayHi = function() {
-    alert(name);
-  }
-}
-```
-
-...But in most cases `class` keyword is used, as it provides great syntax and many additional features.
-
 The basic class syntax looks like this:
 
 ```js
 class MyClass {
-  prop = value; // field
+  prop = value; // property
 
   constructor(...) { // constructor
     // ...
@@ -438,7 +418,7 @@ class MyClass {
   get something(...) {} // getter method
   set something(...) {} // setter method
 
-  [Symbol.iterator]() {} // method with computed name/symbol name
+  [Symbol.iterator]() {} // method with computed name (symbol here)
   // ...
 }
 ```

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

@@ -69,10 +69,10 @@ The function execution "pauses" at the line `(*)` and resumes when the promise s
 
 Let's emphasize: `await` literally suspends the function execution until the promise settles, and then resumes it with the promise result. That doesn't cost any CPU resources, because the JavaScript engine can do other jobs in the meantime: execute other scripts, handle events, etc.
 
-It's just a more elegant syntax of getting the promise result than `promise.then`, easier to read and write.
+It's just a more elegant syntax of getting the promise result than `promise.then`. And, it's easier to read and write.
 
 ````warn header="Can't use `await` in regular functions"
-If we try to use `await` in non-async function, there would be a syntax error:
+If we try to use `await` in a non-async function, there would be a syntax error:
 
 ```js run
 function f() {
@@ -83,7 +83,7 @@ function f() {
 }
 ```
 
-We may get this error if we forget to put `async` before a function. As said, `await` only works inside an `async` function.
+We may get this error if we forget to put `async` before a function. As stated earlier, `await` only works inside an `async` function.
 ````
 
 Let's take the `showAvatar()` example from the chapter <info:promise-chaining> and rewrite it using `async/await`:
@@ -186,7 +186,7 @@ class Waiter {
 
 new Waiter()
   .wait()
-  .then(alert); // 1
+  .then(alert); // 1 (this is the same as (result => alert(result)))
 ```
 The meaning is the same: it ensures that the returned value is a promise and enables `await`.
 

2-ui/1-document/07-modifying-document/5-why-aaa/solution.md

@@ -1,9 +1,9 @@
 The HTML in the task is incorrect. That's the reason of the odd thing.
 
-The browser has to fix it automatically. But there may be no text inside the `<table>`: according to the spec only table-specific tags are allowed. So the browser adds `"aaa"` *before* the `<table>`.
+The browser has to fix it automatically. But there may be no text inside the `<table>`: according to the spec only table-specific tags are allowed. So the browser shows `"aaa"` *before* the `<table>`.
 
 Now it's obvious that when we remove the table, it remains.
 
-The question can be easily answered by exploring the DOM using the browser tools. It shows `"aaa"` before the `<table>`.
+The question can be easily answered by exploring the DOM using the browser tools. You'll see `"aaa"` before the `<table>`.
 
 The HTML standard specifies in detail how to process bad HTML, and such behavior of the browser is correct.

2-ui/3-event-details/4-mouse-drag-and-drop/article.md

@@ -124,7 +124,7 @@ Let's update our algorithm:
 
     ```js
     // onmousemove
-    // ball has position:absoute
+    // ball has position:absolute
     ball.style.left = event.pageX - *!*shiftX*/!* + 'px';
     ball.style.top = event.pageY - *!*shiftY*/!* + 'px';
     ```