Merge pull request #71 from lenchen1112/master

Sync with upstream @b43e954

Author: lenchen1112

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

@@ -211,7 +211,7 @@ for (;;) {
 
 例如，底下的迴圈詢問使用者一連串的數字，當沒有數字被輸入時將會 "中斷（breaking）"：
 
-```js
+```js run
 let sum = 0;
 
 while (true) {

1-js/04-object-basics/05-object-toprimitive/article.md

@@ -45,21 +45,27 @@
 `"default"`
 : 發生於極少情況下，當 "不確定" 運算子會預期是什麼類型時。
 
-    舉個例，二元加法 `+` 可以同時運作在字串（串接）和數值（相加）上，所以字串與數值兩者皆可使用。或當物件使用 `==` 比較字串、數值或符號時，哪種轉換會進行也很不清楚。
+    舉個例，二元加法 `+` 可以同時運作在字串（串接）和數值（相加）上，所以字串與數值兩者皆可使用。因此若二元加法以物件作為引數時，它會使用 `"default"` 提示來轉換。
+
+    同樣地，若物件使用 `==` 比較字串、數值或符號時，哪種轉換會進行也很不清楚，所以會使用 `"default"` 提示。
 
     ```js
-    // 二元加法
-    let total = car1 + car2;
+    // 使用 "default" 提示的二元加法
+    let total = obj1 + obj2;
 
-    // obj == string/number/symbol
+    // obj == number 使用 "default" 提示
     if (user == 1) { ... };
     ```
 
-    大於/小於 運算子 `<>` 一樣可以同時作用於字串和數值上。但它使用 "number" 提示而非 "default"，這是因為歷史因素。
+    大於/小於 運算子 `<>` 一樣可以同時作用於字串和數值上。但它仍使用 "number" 提示而非 "default"，這是因為歷史因素。
+
+    實際上，我們不需要記住這些罕見的細節，因為除了某種例外（`Date` 物件，我們晚點會學到），所有內建物件都實作了和 `"number"` 一樣的 `"default"` 轉換，所以可以同樣方式運作。
 
-    實際上，除了某種物件（`Date` 物件，我們晚點會學到），所有內建物件都實作了和 `"number"` 一樣的 `"default"` 轉換，且我們或許也該這樣做。
+```smart header="No `\"boolean\"` hint"
+請注意 -- 只有三種提示，就那麼簡單。
 
-請注意 -- 只有三種提示，就那麼簡單，不存在 "布林" 提示（所有物件在布林上下文中都是 `true`）等其它的。且若我們對 `"default"` 和 `"number"` 一視同仁，如同大多內建物件那樣，那將只有兩種轉換了。
+不存在 "布林" 提示（所有物件在布林上下文中都是 `true`）等等其它的轉換。且若我們將 `"default"` 和 `"number"` 一視同仁，如同大多內建物件那樣，那將只有兩種轉換了。
+```
 
 **要做轉換時，JavaScript 試著找尋並呼叫三種物件方法：**
 
@@ -110,7 +116,29 @@ alert(user + 500); // hint: default -> 1500
 - 對於 "string" 提示，`toString -> valueOf`。
 - 否則，`valueOf -> toString`。
 
-舉個例，這個 `user` 採用 `toString` 與 `valueOf` 做了如同前述的事情：
+這些方法必須回傳一個原生值，若 `toString` 或 `valueOf` 回傳一個物件，則它將被忽略（視同根本不存在這個方法）。
+
+每個物件會有下列預設的 `toString` 與 `valueOf` 方法：
+
+- `toString` 方法回傳一個字串 `"[object Object]"`。
+- `valueOf` 方法回傳物件自身。
+
+在此演示一下：
+
+```js run
+let user = {name: "John"};
+
+alert(user); // [object Object]
+alert(user.valueOf() === user); // true
+```
+
+所以若我們試圖將某個物件作為字串使用，像是用於 `alert` 等其它地方，那我們預設將看到 `[object Object]`。
+
+為了避免搞混，而在這邊提到預設的 `valueOf` 只是為了完整性考量。如同你所見，它回傳了該物件本身從而被忽略了。別問我為什麼，那是歷史因素。所以我們可以假設它根本不存在。
+
+來實作這些方法吧。
+
+舉個例，這個 `user` 使用 `toString` 和 `valueOf` 的組合做了如同上述的事，而不是用 `Symbol.toPrimitive`：
 
 ```js run
 let user = {
@@ -167,35 +195,41 @@ alert(user + 500); // toString -> John500
 相對地，`Symbol.toPrimitive` *必須* 回傳一個原生類型，否則就會產生錯誤。
 ```
 
-## 進一步的操作
+## 進一步的轉換
 
-一個發起轉換的運算獲得了原生類型，然後繼續運作，並在需要時再套用進一步的轉換。
+如同我們所知的，許多運算子與函式都會做類型轉換，像是：乘法 `*` 會轉換運算元為數值。
+
+若我們傳入一個物件作為引數，那將會進行兩個步驟：
+1. 物件被轉為原生值（使用上述的規則）。
+2. 若轉完的原生值並非正確類型，就再進行轉換。
 
 舉個例：
 
-- 數學運算，除了二元加法以外，將會轉換該原生類型為數值：
+```js run
+let obj = {
+  // 在少了其他方法的情況下，toString 處理所有的轉換
+  toString() {
+    return "2";
+  }
+};
 
-    ```js run
-    let obj = {
-      // 在少了其他方法的情況下，toString 處理所有的轉換
-      toString() {
-        return "2";
-      }
-    };
+alert(obj * 2); // 4，物件被轉為原生類型 "2"，然後乘法會讓它再變成一個數值
+```
 
-    alert(obj * 2); // 4，物件被轉為原生類型 "2"，然後乘法會讓它再變成一個數值
-    ```
+1. `obj * 2` 的乘法運算會先轉換該物件為原生值（也就是變成一個字串 `"2"`）。
+2. 然後 `"2" * 2` 會變成 `2 * 2`（字串被轉換為數值）。
 
-- 二元加法在同樣情境時會連接字串：
-    ```js run
-    let obj = {
-      toString() {
-        return "2";
-      }
-    };
+二元加法在同樣情境時會連接字串，並欣然接受轉完的字串：
 
-    alert(obj + 2); // 22（轉換成原生類型會回傳一個字串 => 串接）
-    ```
+```js run
+let obj = {
+  toString() {
+    return "2";
+  }
+};
+
+alert(obj + 2); // 22（"2" + 2），轉換為原生值時回傳一個字串 => 串接
+```
 
 ## 總結
 

1-js/05-data-types/05-array-methods/6-calculator-extendable/solution.md

@@ -1,5 +1,3 @@
 
 - Please note how methods are stored. They are simply added to `this.methods` property.
 - All tests and numeric conversions are done in the `calculate` method. In future it may be extended to support more complex expressions.
-
-[js src="_js/solution.js"]

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

@@ -142,15 +142,17 @@ for (let char of str) {
 
 For deeper understanding let's see how to use an iterator explicitly.
 
-We'll iterate over a string in exactlly the same way as `for..of`, but with direct calls. This code creates a string iterator and gets values from it "manually":
+We'll iterate over a string in exactly the same way as `for..of`, but with direct calls. This code creates a string iterator and gets values from it "manually":
 
 ```js run
 let str = "Hello";
 
 // does the same as
 // for (let char of str) alert(char);
 
+*!*
 let iterator = str[Symbol.iterator]();
+*/!*
 
 while (true) {
   let result = iterator.next();
@@ -212,7 +214,7 @@ let arr = Array.from(arrayLike); // (*)
 alert(arr.pop()); // World (method works)
 ```
 
-`Array.from` at the line `(*)` takes the object, examines it for being an iterable or array-like, then makes a new array and copies there all items.
+`Array.from` at the line `(*)` takes the object, examines it for being an iterable or array-like, then makes a new array and copies all items to it.
 
 The same happens for an iterable:
 
@@ -268,7 +270,7 @@ for (let char of str) {
 alert(chars);
 ```
 
-...But is shorter.    
+...But it is shorter.    
 
 We can even build surrogate-aware `slice` on it:
 

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

@@ -61,7 +61,7 @@ So, this will also work:
 setTimeout("alert('Hello')", 1000);
 ```
 
-But using strings is not recommended, use functions instead of them, like this:
+But using strings is not recommended, use arrow functions instead of them, like this:
 
 ```js run no-beautify
 setTimeout(() => alert('Hello'), 1000);
@@ -184,7 +184,7 @@ Let's compare two code fragments. The first one uses `setInterval`:
 ```js
 let i = 1;
 setInterval(function() {
-  func(i);
+  func(i++);
 }, 100);
 ```
 
@@ -193,12 +193,12 @@ The second one uses nested `setTimeout`:
 ```js
 let i = 1;
 setTimeout(function run() {
-  func(i);
+  func(i++);
   setTimeout(run, 100);
 }, 100);
 ```
 
-For `setInterval` the internal scheduler will run `func(i)` every 100ms:
+For `setInterval` the internal scheduler will run `func(i++)` every 100ms:
 
 ![](setinterval-interval.svg)
 

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

@@ -83,10 +83,12 @@ let user = {
 
 setTimeout(() => user.sayHi(), 1000);
 
-// ...within 1 second
-user = { sayHi() { alert("Another user in setTimeout!"); } };
+// ...the value of user changes within 1 second
+user = {
+  sayHi() { alert("Another user in setTimeout!"); }
+};
 
-// Another user in setTimeout?!?
+// Another user in setTimeout!
 ```
 
 The next solution guarantees that such thing won't happen.
@@ -159,9 +161,16 @@ let user = {
 let sayHi = user.sayHi.bind(user); // (*)
 */!*
 
+// can run it without an object
 sayHi(); // Hello, John!
 
 setTimeout(sayHi, 1000); // Hello, John!
+
+// even if the value of user changes within 1 second
+// sayHi uses the pre-bound value
+user = {
+  sayHi() { alert("Another user in setTimeout!"); }
+};
 ```
 
 In the line `(*)` we take the method `user.sayHi` and bind it to `user`. The `sayHi` is a "bound" function, that can be called alone or passed to `setTimeout` -- doesn't matter, the context will be right.

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

@@ -7,7 +7,7 @@ So we can create new functionality on top of the existing.
 
 ## The "extends" keyword
 
-Let's say with have class `Animal`:
+Let's say we have class `Animal`:
 
 ```js
 class Animal {
@@ -40,7 +40,7 @@ The syntax to extend another class is: `class Child extends Parent`.
 
 Let's create `class Rabbit` that inherits from `Animal`:
 
-```js
+```js run
 *!*
 class Rabbit extends Animal {
 */!*

1-js/09-classes/06-instanceof/article.md

@@ -2,7 +2,7 @@
 
 The `instanceof` operator allows to check whether an object belongs to a certain class. It also takes inheritance into account.
 
-Such a check may be necessary in many cases, here we'll use it for building a *polymorphic* function, the one that treats arguments differently depending on their type.
+Such a check may be necessary in many cases. Here we'll use it for building a *polymorphic* function, the one that treats arguments differently depending on their type.
 
 ## The instanceof operator [#ref-instanceof]
 
@@ -46,7 +46,7 @@ alert( arr instanceof Object ); // true
 
 Please note that `arr` also belongs to the `Object` class. That's because `Array` prototypically inherits from `Object`.
 
-Normally, `instanceof` operator examines the prototype chain for the check. We can also set a custom logic in the static method `Symbol.hasInstance`.
+Normally, `instanceof` examines the prototype chain for the check. We can also set a custom logic in the static method `Symbol.hasInstance`.
 
 The algorithm of `obj instanceof Class` works roughly as follows:
 
@@ -68,7 +68,7 @@ The algorithm of `obj instanceof Class` works roughly as follows:
     alert(obj instanceof Animal); // true: Animal[Symbol.hasInstance](obj) is called
     ```
 
-2. Most classes do not have `Symbol.hasInstance`. In that case, the standard logic is used: `obj instanceOf Class` checks whether `Class.prototype` equals to one of prototypes in the `obj` prototype chain.
+2. Most classes do not have `Symbol.hasInstance`. In that case, the standard logic is used: `obj instanceOf Class` checks whether `Class.prototype` is equal to one of the prototypes in the `obj` prototype chain.
 
     In other words, compare one after another:
     ```js
@@ -107,7 +107,7 @@ By the way, there's also a method [objA.isPrototypeOf(objB)](mdn:js/object/isPro
 
 It's funny, but the `Class` constructor itself does not participate in the check! Only the chain of prototypes and `Class.prototype` matters.
 
-That can lead to interesting consequences when `prototype` property is changed after the object is created.
+That can lead to interesting consequences when a `prototype` property is changed after the object is created.
 
 Like here:
 
@@ -186,7 +186,7 @@ let user = {
 alert( {}.toString.call(user) ); // [object User]
 ```
 
-For most environment-specific objects, there is such a property. Here are few browser specific examples:
+For most environment-specific objects, there is such a property. Here are some browser specific examples:
 
 ```js run
 // toStringTag for the environment-specific object and class:

1-js/11-async/04-promise-error-handling/article.md

@@ -166,11 +166,11 @@ new Promise(function() {
 
 In case of an error, the promise becomes rejected, and the execution should jump to the closest rejection handler. But there is none. So the error gets "stuck". There's no code to handle it.
 
-In practice, just like with regular unhandled errors in code, it means that something has terribly gone wrong.
+In practice, just like with regular unhandled errors in code, it means that something has gone terribly wrong.
 
-What happens when a regular error occurs and is not caught by `try..catch`? The script dies with a message in console. Similar thing happens with unhandled promise rejections.
+What happens when a regular error occurs and is not caught by `try..catch`? The script dies with a message in the console. A similar thing happens with unhandled promise rejections.
 
-JavaScript engine tracks such rejections and generates a global error in that case. You can see it in the console if you run the example above.
+The JavaScript engine tracks such rejections and generates a global error in that case. You can see it in the console if you run the example above.
 
 In the browser we can catch such errors using the event `unhandledrejection`:
 
@@ -201,4 +201,4 @@ In non-browser environments like Node.js there are other ways to track unhandled
 - `.catch` handles errors in promises of all kinds: be it a `reject()` call, or an error thrown in a handler.
 - We should place `.catch` exactly in places where we want to handle errors and know how to handle them. The handler should analyze errors (custom error classes help) and rethrow unknown ones (maybe they are programming mistakes).
 - It's ok not to use `.catch` at all, if there's no way to recover from an error.
-- In any case we should have the `unhandledrejection` event handler (for browsers, and analogs for other environments), to track unhandled errors and inform the user (and probably our server) about the them, so that our app never "just dies".
+- In any case we should have the `unhandledrejection` event handler (for browsers, and analogs for other environments) to track unhandled errors and inform the user (and probably our server) about them, so that our app never "just dies".