Merge pull request #69 from lenchen1112/master

Sync with upstream @601d958

Author: lenchen1112

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

@@ -168,7 +168,7 @@ There are buttons for it at the top of the right panel. Let's engage them.
 <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.
 
-    The "Step" command goes into it and and pauses the execution at its first line, while "Step over" executes the nested function call invisibly, skipping the function internals.
+    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.
 
     The execution is then paused immediately after that function.
 

1-js/05-data-types/03-string/article.md

@@ -394,7 +394,7 @@ There are 3 methods in JavaScript to get a substring: `substring`, `substr` and
 
     ```js run
     let str = "st*!*ringify*/!*";
-    alert( str.slice(2) ); // ringify, from the 2nd position till the end
+    alert( str.slice(2) ); // 'ringify', from the 2nd position till the end
     ```
 
     Negative values for `start/end` are also possible. They mean the position is counted from the string end:
@@ -403,7 +403,7 @@ There are 3 methods in JavaScript to get a substring: `substring`, `substr` and
     let str = "strin*!*gif*/!*y";
 
     // start at the 4th position from the right, end at the 1st from the right
-    alert( str.slice(-4, -1) ); // gif
+    alert( str.slice(-4, -1) ); // 'gif'
     ```
 
 `str.substring(start [, end])`
@@ -435,14 +435,14 @@ There are 3 methods in JavaScript to get a substring: `substring`, `substr` and
 
     ```js run
     let str = "st*!*ring*/!*ify";
-    alert( str.substr(2, 4) ); // ring, from the 2nd position get 4 characters
+    alert( str.substr(2, 4) ); // 'ring', from the 2nd position get 4 characters
     ```
 
     The first argument may be negative, to count from the end:
 
     ```js run
     let str = "strin*!*gi*/!*fy";
-    alert( str.substr(-4, 2) ); // gi, from the 4th position get 2 characters
+    alert( str.substr(-4, 2) ); // 'gi', from the 4th position get 2 characters
     ```
 
 Let's recap these methods to avoid any confusion:

1-js/05-data-types/05-array-methods/4-sort-back/task.md

@@ -2,12 +2,12 @@ importance: 4
 
 ---
 
-# Sort in the reverse order
+# Sort in decreasing order
 
 ```js
 let arr = [5, 2, 1, -10, 8];
 
-// ... your code to sort it in the reverse order
+// ... your code to sort it in decreasing order
 
 alert( arr ); // 8, 5, 2, 1, -10
 ```

1-js/05-data-types/05-array-methods/article.md

@@ -36,7 +36,7 @@ That's natural, because `delete obj.key` removes a value by the `key`. It's all
 
 So, special methods should be used.
 
-The [arr.splice(str)](mdn:js/Array/splice) method is a swiss army knife for arrays. It can do everything: insert, remove and replace elements.
+The [arr.splice(start)](mdn:js/Array/splice) method is a swiss army knife for arrays. It can do everything: insert, remove and replace elements.
 
 The syntax is:
 
@@ -268,7 +268,7 @@ alert( arr.includes(NaN) );// true (correct)
 
 Imagine we have an array of objects. How do we find an object with the specific condition?
 
-Here the [arr.find](mdn:js/Array/find) method comes in handy.
+Here the [arr.find(fn)](mdn:js/Array/find) method comes in handy.
 
 The syntax is:
 ```js
@@ -574,7 +574,7 @@ The calculation flow:
 
 Or in the form of a table, where each row represents a function call on the next array element:
 
-|   |`sum`|`current`|`result`|
+|   |`sum`|`current`|result|
 |---|-----|---------|---------|
 |the first call|`0`|`1`|`1`|
 |the second call|`1`|`2`|`3`|

1-js/05-data-types/09-keys-values-entries/article.md

@@ -11,7 +11,7 @@ They are supported for:
 
 - `Map`
 - `Set`
-- `Array` (except `arr.values()`)
+- `Array`
 
 Plain objects also support similar methods, but the syntax is a bit different.
 

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

@@ -187,7 +187,7 @@ The destructuring assignment also works with objects.
 The basic syntax is:
 
 ```js
-let {var1, var2} = {var1:…, var2…}
+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 `{...}`.

1-js/05-data-types/12-json/article.md

@@ -425,9 +425,9 @@ alert( numbers[1] ); // 1
 Or for nested objects:
 
 ```js run
-let user = '{ "name": "John", "age": 35, "isAdmin": false, "friends": [0,1,2,3] }';
+let userData = '{ "name": "John", "age": 35, "isAdmin": false, "friends": [0,1,2,3] }';
 
-user = JSON.parse(user);
+let user = JSON.parse(userData);
 
 alert( user.friends[1] ); // 1
 ```

1-js/06-advanced-functions/01-recursion/article.md

@@ -459,6 +459,7 @@ let list = { value: 1 };
 list.next = { value: 2 };
 list.next.next = { value: 3 };
 list.next.next.next = { value: 4 };
+list.next.next.next.next = null;
 ```
 
 Here we can even more clearer see that there are multiple objects, each one has the `value` and `next` pointing to the neighbour. The `list` variable is the first object in the chain, so following `next` pointers from it we can reach any element.

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

@@ -351,7 +351,7 @@ Please note the additional `[[Environment]]` property is covered here. We didn't
 
     ![](lexenv-nested-makecounter-3.svg)
 
-    Please note that on this step the inner function was created, but not yet called. The code inside `function() { return count++; }` is not running.
+    Please note that on this step the inner function was created, but not yet called. The code inside `return count++;` is not running.
 
 4. As the execution goes on, the call to `makeCounter()` finishes, and the result (the tiny nested function) is assigned to the global variable `counter`:
 
@@ -565,7 +565,8 @@ function f() {
 */!*
 }
 
-let g = f(); // g is reachable, and keeps the outer lexical environment in memory
+let func = f(); // func gets a reference to g
+// so it stays and memory and its outer lexical environment stays as well
 ```
 
 Please note that if `f()` is called many times, and resulting functions are saved, then all corresponding Lexical Environment objects will also be retained in memory. All 3 of them in the code below:
@@ -595,10 +596,9 @@ function f() {
   return g;
 }
 
-let g = f(); // while g is alive
-// their corresponding Lexical Environment lives
+let func = f(); // while func has a reference to g, it stays in memory
 
-g = null; // ...and now the memory is cleaned up
+func = null; // ...and now the memory is cleaned up
 ```
 
 ### Real-life optimizations

1-js/06-advanced-functions/08-settimeout-setinterval/article.md

@@ -288,7 +288,7 @@ For server-side JavaScript, that limitation does not exist, and there exist othe
 
 - Methods `setTimeout(func, delay, ...args)` and `setInterval(func, delay, ...args)` allow us to run the `func` once/regularly after `delay` milliseconds.
 - To cancel the execution, we should call `clearTimeout/clearInterval` with the value returned by `setTimeout/setInterval`.
-- Nested `setTimeout` calls is a more flexible alternative to `setInterval`, allowing us to set the time *between* executions more precisely.
+- Nested `setTimeout` calls are a more flexible alternative to `setInterval`, allowing us to set the time *between* executions more precisely.
 - Zero delay scheduling with `setTimeout(func, 0)` (the same as `setTimeout(func)`) is used to schedule the call "as soon as possible, but after the current script is complete".
 - The browser limits the minimal delay for five or more nested call of `setTimeout` or for `setInterval` (after 5th call) to 4ms. That's for historical reasons.
 

1-js/06-advanced-functions/09-call-apply-decorators/04-throttle/_js.view/test.js

@@ -44,4 +44,20 @@ describe("throttle(f, 1000)", function() {
     this.clock.restore();
   });
 
-});
+});
+
+describe('throttle', () => {
+
+  it('runs a forwarded call once', done => {
+    let log = '';
+    const f = str => log += str;
+    const f10 = throttle(f, 10);
+    f10('once');
+
+    setTimeout(() => {
+      assert.equal(log, 'once');
+      done();
+    }, 20);
+  });
+
+});

1-js/06-advanced-functions/10-bind/6-ask-partial/task.md

@@ -8,7 +8,7 @@ The task is a little more complex variant of <info:task/question-use-bind>.
 
 The `user` object was modified. Now instead of two functions `loginOk/loginFail`, it has a single function `user.login(true/false)`.
 
-What to pass `askPassword` in the code below, so that it calls `user.login(true)` as `ok` and `user.login(false)` as `fail`?
+What should we pass `askPassword` in the code below, so that it calls `user.login(true)` as `ok` and `user.login(false)` as `fail`?
 
 ```js
 function askPassword(ok, fail) {

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

@@ -98,7 +98,7 @@ Functions provide a built-in method [bind](mdn:js/Function/bind) that allows to
 The basic syntax is:
 
 ```js
-// more complex syntax will be little later
+// more complex syntax will come a little later
 let boundFunc = func.bind(context);
 ```
 

1-js/06-advanced-functions/12-arrow-functions/article.md

@@ -118,9 +118,9 @@ Here we had to create additional variables `args` and `ctx` so that the function
 
 Arrow functions:
 
-- Do not have `this`.
-- Do not have `arguments`.
-- Can't be called with `new`.
-- (They also don't have `super`, but we didn't study it. Will be in the chapter <info:class-inheritance>).
+- Do not have `this`
+- Do not have `arguments`
+- Can't be called with `new`
+- They also don't have `super`, but we didn't study it yet. We will on the chapter <info:class-inheritance>
 
-That's because they are meant for short pieces of code that do not have their own "context", but rather works in the current one. And they really shine in that use case.
+That's because they are meant for short pieces of code that do not have their own "context", but rather work in the current one. And they really shine in that use case.

1-js/07-object-properties/01-property-descriptors/article.md

@@ -3,7 +3,7 @@
 
 As we know, objects can store properties.
 
-Till now, a property was a simple "key-value" pair to us. But an object property is actually a more flexible and powerful thing.
+Until now, a property was a simple "key-value" pair to us. But an object property is actually a more flexible and powerful thing.
 
 In this chapter we'll study additional configuration options, and in the next we'll see how to invisibly turn them into getter/setter functions.
 
@@ -134,7 +134,7 @@ let user = { };
 Object.defineProperty(user, "name", {
 *!*
   value: "John",
-  // for new properties need to explicitly list what's true
+  // for new properties we need to explicitly list what's true
   enumerable: true,
   configurable: true
 */!*
@@ -148,7 +148,7 @@ user.name = "Pete"; // Error
 
 Now let's add a custom `toString` to `user`.
 
-Normally, a built-in `toString` for objects is non-enumerable, it does not show up in `for..in`. But if we add `toString` of our own, then by default it shows up in `for..in`, like this:
+Normally, a built-in `toString` for objects is non-enumerable, it does not show up in `for..in`. But if we add a `toString` of our own, then by default it shows up in `for..in`, like this:
 
 ```js run
 let user = {
@@ -162,7 +162,7 @@ let user = {
 for (let key in user) alert(key); // name, toString
 ```
 
-If we don't like it, then we can set `enumerable:false`. Then it won't appear in `for..in` loop, just like the built-in one:
+If we don't like it, then we can set `enumerable:false`. Then it won't appear in a `for..in` loop, just like the built-in one:
 
 ```js run
 let user = {

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

@@ -3,7 +3,7 @@
 
 There are two kinds of properties.
 
-The first kind is *data properties*. We already know how to work with them. All properties that we've been using till now were data properties.
+The first kind is *data properties*. We already know how to work with them. All properties that we've been using until now were data properties.
 
 The second type of properties is something new. It's *accessor properties*. They are essentially functions that work on getting and setting a value, but look like regular properties to an external code.
 
@@ -189,9 +189,9 @@ Technically, external code is able to access the name directly by using `user._n
 
 ## Using for compatibility
 
-One of the great uses of accessors -- they allow to take control over a "regular" data property at any moment by replacing it with getter and setter and tweak its behavior.
+One of the great uses of accessors is that they allow to take control over a "regular" data property at any moment by replacing it with a getter and a setter and tweak its behavior.
 
-Imagine, we started implementing user objects using data properties `name` and `age`:
+Imagine we started implementing user objects using data properties `name` and `age`:
 
 ```js
 function User(name, age) {

1-js/08-prototypes/01-prototype-inheritance/2-search-algorithm/task.md

@@ -6,7 +6,7 @@ importance: 5
 
 The task has two parts.
 
-We have objects:
+Given the following objects:
 
 ```js
 let head = {

1-js/08-prototypes/01-prototype-inheritance/3-proto-and-this/task.md

@@ -2,7 +2,7 @@ importance: 5
 
 ---
 
-# Where it writes?
+# Where does it write?
 
 We have `rabbit` inheriting from `animal`.
 

1-js/08-prototypes/01-prototype-inheritance/4-hamster-proto/task.md

@@ -2,11 +2,11 @@ importance: 5
 
 ---
 
-# Why two hamsters are full?
+# Why are both hamsters full?
 
 We have two hamsters: `speedy` and `lazy` inheriting from the general `hamster` object. 
 
-When we feed one of them, the other one is also full. Why? How to fix it?
+When we feed one of them, the other one is also full. Why? How can we fix it?
 
 ```js run
 let hamster = {

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

@@ -34,7 +34,7 @@ rabbit.__proto__ = animal;
 ```smart header="`__proto__` is a historical getter/setter for `[[Prototype]]`"
 Please note that `__proto__` is *not the same* as `[[Prototype]]`. That's a getter/setter for it.
 
-It exists for historical reasons, in modern language it is replaced with functions `Object.getPrototypeOf/Object.setPrototypeOf` that also get/set the prototype. We'll study the reasons for that and these functions later.
+It exists for historical reasons. In modern language it is replaced with functions `Object.getPrototypeOf/Object.setPrototypeOf` that also get/set the prototype. We'll study the reasons for that and these functions later.
 
 By the specification, `__proto__` must only be supported by browsers, but in fact all environments including server-side support it. For now, as `__proto__` notation is a little bit more intuitively obvious, we'll use it in the examples.
 ```
@@ -203,7 +203,7 @@ Here in the line `(*)` the property `admin.fullName` has a getter in the prototy
 
 ## The value of "this"
 
-An interesting question may arise in the example above: what's the value of `this` inside `set fullName(value)`? Where the properties `this.name` and `this.surname` are written: into `user` or `admin`?
+An interesting question may arise in the example above: what's the value of `this` inside `set fullName(value)`? Where are the properties `this.name` and `this.surname` written: into `user` or `admin`?
 
 The answer is simple: `this` is not affected by prototypes at all.
 
@@ -246,13 +246,13 @@ The resulting picture:
 
 ![](proto-animal-rabbit-walk-3.svg)
 
-If we had other objects like `bird`, `snake` etc inheriting from `animal`, they would also gain access to methods of `animal`. But `this` in each method call would be the corresponding object, evaluated at the call-time (before dot), not `animal`. So when we write data into `this`, it is stored into these objects.
+If we had other objects, like `bird`, `snake`, etc., inheriting from `animal`, they would also gain access to methods of `animal`. But `this` in each method call would be the corresponding object, evaluated at the call-time (before dot), not `animal`. So when we write data into `this`, it is stored into these objects.
 
 As a result, methods are shared, but the object state is not.
 
 ## for..in loop
 
-The `for..in` loops over inherited properties too.
+The `for..in` loop iterates over inherited properties too.
 
 For instance:
 
@@ -267,7 +267,7 @@ let rabbit = {
 };
 
 *!*
-// Object.keys only return own keys
+// Object.keys only returns own keys
 alert(Object.keys(rabbit)); // jumps
 */!*
 

1-js/08-prototypes/02-function-prototype/1-changing-prototype/task.md

@@ -20,7 +20,7 @@ alert( rabbit.eats ); // true
 ```
 
 
-1. We added one more string (emphasized), what `alert` shows now?
+1. We added one more string (emphasized). What will `alert` show now?
 
     ```js
     function Rabbit() {}
@@ -54,7 +54,7 @@ alert( rabbit.eats ); // true
     alert( rabbit.eats ); // ?
     ```
 
-3. Like this (replaced one line)?
+3. And like this (replaced one line)?
 
     ```js
     function Rabbit() {}

1-js/08-prototypes/02-function-prototype/article.md

@@ -2,7 +2,7 @@
 
 Remember, new objects can be created with a constructor function, like `new F()`.
 
-If `F.prototype` is an object, then `new` operator uses it to set `[[Prototype]]` for the new object.
+If `F.prototype` is an object, then the `new` operator uses it to set `[[Prototype]]` for the new object.
 
 ```smart
 JavaScript had prototypal inheritance from the beginning. It was one of the core features of the language.
@@ -158,9 +158,9 @@ Rabbit.prototype = {
 
 In this chapter we briefly described the way of setting a `[[Prototype]]` for objects created via a constructor function. Later we'll see more advanced programming patterns that rely on it.
 
-Everything is quite simple, just few notes to make things clear:
+Everything is quite simple, just a few notes to make things clear:
 
-- The `F.prototype` property (don't mess with `[[Prototype]]`) sets `[[Prototype]]` of new objects when `new F()` is called.
+- The `F.prototype` property (don't mistake it for `[[Prototype]]`) sets `[[Prototype]]` of new objects when `new F()` is called.
 - The value of `F.prototype` should be either an object or `null`: other values won't work.
 -  The `"prototype"` property only has such a special effect when set on a constructor function, and invoked with `new`.