Sync with upstream @ 3dd8ca0 (#42)

* modified sub headings for clarity and to avoid confusion

* Update article.md

* Update task.md

fix typo

* Update article.md

Change to wording about maximum recursion depth.

* Update article.md

* Update article.md

Correct spelling of "standardized".

* Fix typo

* minor

* closes #1271

* minor

* clarify type conversion headings

* minor

* improve description

Change the order between ´body´ and ´step´. Also delete the phrase '... but before the condition check', which seems a bit confusing.

* Update article.md

Maybe this is what you want. "Complexity" is singular, so if that's the antecedent, one would use "was".

* fixes #1261

* Fix typo

fix typo in comment to match code example

* Typo/grammar fix

* fixed missing pronoun 'it'

fixed missing pronoun 'it'.

* fixed missing pronoun 'it'

fixed missing pronoun 'it'

* Update article.md

fixed grammaticalmistakes, i.e. changed 'And' to 'and', added missing pronoun 'it' after 'to'.

* Update article.md

* Fixed spelling error

So here JavaScript assumes that we have a code block, but why there's an error. --> Makes no sense so replaced "but" with "that's"

* fixes

* minor

* Update article.md

Better grammatically.

* typo

* minor

* fixes

* fix minor English language issues

* fix typo

* Some minor corrections

* Is it

* Update article.md

Wording of initial explanation of spread operator.

* Typo

* there must be exactly the origin there.

* Fixed a typo

* Update article.md

1. Since is general statement, thought might be better to use general function name.
2. "Do the following steps" is a bit awkward, in that usually one doesn't "do" steps (but rather "takes", or "follows", or "executes" steps, perhaps). But it does convey the meaning, and perhaps it's a relatively new usage in business or tech that I'm not familiar with. For me, it comes off a bit awkward. Leaving out "steps" works grammatically and preserves the sense. Or could find another verb to replace "do" -- but nothing perfect came to mind. Not that bad the way it is, but since I was already changing the sentence...

* Update article.md

Says "is the same object as:", but what's below is an assignment (that includes an object). I didn't have any problem understanding it, didn't even notice it at first, but I thought it would be more accurate this way without sacrificing clarity.

* Update article.md

Qualify that while cachingDecorator() will now work with any number of arguments, the hash() function given will not. Or, perhaps better, could just change the hash function to something like:

function hash(args) {
  return [...args].join();
}

* Update article.md

* minor

* fixes

* grammar fix

removed 'is'

* minor

* minor

* minor

* minor

* minor

* minor

* minor

* minor

* closes #1310

* closes #1309

* closes #1309

* closes #1309

* minor

* closes #1308

* closes #1294

* Fix typo in Proxy and Reflect article

* Update task.md

Wording was ungrammatical and hard to understand. I made my best guess as to what you want to say. However, it is not clear from the description or the examples whether the debounce wrapper should inhibit calls attempted ms milliseconds after the last call that wasn't ignored, or ms milliseconds after the last call that was attempted, even if it was ignored. I would think it would be the former, but the example could go either way. If the f(4) example used 1000 or 1001 ms and still runs, that would clear it up. If it has to be 1100 like it is, that would suggest that it's the second scenario above. In my propsed change I preserved the ambiguity.

* closes #1220

* Update MDN docs link for tagged templates

* Update article.md

As per issue comment thread #1282: 
Clarifying "current code" for zero delay setInterval. 
Plus minor edit of ordering of terms for greater consistency.
Plus minor grammatical fixes.

* an -> a

* WIP

* fixes #1316

* closes #1318

* minor

* minor

* WIP

* WIP

* regexp

* WIP

* reg->regexp

* WIP

* Typo fix

* minor

* form

* Typo fix

* fixes

* fixes

* fix

* Fix minor grammatical errors

* Minor grammatical fixes

* minor

Author: lenchen1112

1-js/01-getting-started/2-manuals-specifications/article.md

@@ -1,6 +1,6 @@
-# 手冊以及規格書
+# 操作手冊和規格書
 
-這本書是個 _教程_，主要是幫助你漸漸地學會這門語言，一旦你熟悉了基礎，你將會需要更多其他的資源來幫助你。
+這本書是個 *教程*，主要是幫助你漸漸地學會這門語言，一旦你熟悉了基礎，你將會需要更多其他的資源。
 
 ## 規格書
 
@@ -12,17 +12,17 @@
 
 如果你想知道最尖端的功能，包含那些 "即將成為標準"（所謂 "stage 3"）的功能，可以看一下 <https://github.com/tc39/proposals>。
 
-或者，假如你在開發瀏覽器相關的功能，我們也有在此教程的 [第二部分](info:browser-environment) 介紹相關的規格書。
+同樣地，假如你在開發瀏覽器相關的功能，我們也有在此教程的 [第二部分](info:browser-environment) 介紹相關的規格書。
 
-## 手冊
+## 操作手冊
 
--   **MDN (Mozilla) JavaScript Reference** 是一個包含了範例以及其他資訊的手冊，很適合拿來獲取個別函式或是方法的深入資訊。
+- **MDN (Mozilla) JavaScript Reference** 是一個包含了範例以及其他資訊的操作手冊，很適合拿來獲取個別函式或是方法的深入資訊。
 
     你可以在這裡找到 <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference>。
 
     不過，透過網路搜尋通常會是較好的選擇。使用在搜尋列打入 "MDN [關鍵字]" 的方式，比如你要搜尋 `parseInt` 這個函式，可以用 <https://google.com/search?q=MDN+parseInt>。
 
-*   **MSDN** – 微軟釋出的手冊，包含了一堆 JavaScript（通常是指 JScript）的資訊。如果你需要開發跟 Internet Explorer 有關的功能，最好參考此處： <http://msdn.microsoft.com/>。
+- **MSDN** – 微軟釋出的操作手冊，包含了一堆 JavaScript（通常是指 JScript）的資訊。如果你需要開發跟 Internet Explorer 有關的功能，最好參考此處： <http://msdn.microsoft.com/>。
 
     當然，我們也可以透過網路搜尋來找到我們需要的資訊，比如 "RegExp MSDN" 或是 "RegExp MSDN jscript"。
 
@@ -32,9 +32,10 @@ JavaScript 是一個持續開發中的語言，它定期會被加入一些新功
 
 想知道瀏覽器或是其他引擎的支援程度，可以參考：
 
--   <http://caniuse.com> - 列出每一個功能的支援程度，比如：查找哪個引擎支援現代的編碼功能：<http://caniuse.com/#feat=cryptography>。
--   <https://kangax.github.io/compat-table> - 一個列出所有功能以及每個引擎支援程度的表。
+- <http://caniuse.com> - 列出每一個功能的支援程度，比如：查找哪個引擎支援現代的編碼功能：<http://caniuse.com/#feat=cryptography>。
+- <https://kangax.github.io/compat-table> - 一個列出所有功能以及每個引擎支援程度的表。
 
 所有這些資訊對於實務開發都是很有用的，因為他們包含了非常有價值的資訊，比如支援程度跟語言的細節等。
 
 當你需要比較深入的資訊或是需要了解一些特定的功能時，請記得使用這些資訊（或是此頁）。
+

1-js/02-first-steps/06-type-conversions/article.md

@@ -128,9 +128,9 @@ alert( Boolean(" ") ); // 空白，也是 true（任何非空字串都是 true
 
 三種最為廣泛使用的類型轉換是：轉字串、轉數值和轉布林。
 
-**`String Conversion`** -- 用於當我們輸出某些東西時，可使用 `String(value)` 來轉換，原生值的字串轉換通常是很直觀的。
+**`字串轉換`** -- 用於當我們輸出某些東西時，可使用 `String(value)` 來轉換，原生值的字串轉換通常是很直觀的。
 
-**`Numeric Conversion`** -- 用於數學運算，可使用 `Number(value)` 來轉換。
+**`數值轉換`** -- 用於數學運算，可使用 `Number(value)` 來轉換。
 
 按照以下規則轉換：
 
@@ -141,7 +141,7 @@ alert( Boolean(" ") ); // 空白，也是 true（任何非空字串都是 true
 |<code>true&nbsp;/&nbsp;false</code> | `1 / 0` |
 | `string` | 字串 "依原樣" 讀取並忽略頭尾空白，若為空字串則為 `0`，有錯誤則成為 `NaN`。 |
 
-**`Boolean Conversion`** -- 用於邏輯運算，可使用 `Boolean(value)` 來轉換。
+**`布林轉換`** -- 用於邏輯運算，可使用 `Boolean(value)` 來轉換。
 
 規則是：
 

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

@@ -26,7 +26,7 @@
     alert( y - x ); // 2，二元減號運算子套用減法
     ```
 
-    正式地說，這邊提及的是兩種使用同個符號，意義卻完全不同的運算子：一元負號運算子（單一個運算元，正負轉換）和二元減號運算子（兩個運算元，減法）。
+    正式地說，上例中的兩個運算子使用同一個符號，但意義卻完全不同：一元負號運算子（單一個運算元，正負轉換）和二元減號運算子（兩個運算元，一對一的數值減法）。
 
 ## 字串連接，二元運算子 +
 

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

@@ -98,7 +98,7 @@ It's common that an object method needs to access the information stored in the
 
 For instance, the code inside `user.sayHi()` may need the name of the `user`.
 
-**To access the object, a method can use the `this` keyword.**
+**To access the object, a method can use `this` keyword.**
 
 The value of `this` is the object "before dot", the one used to call the method.
 
@@ -167,9 +167,9 @@ If we used `this.name` instead of `user.name` inside the `alert`, then the code
 
 ## "this" is not bound
 
-In JavaScript, "this" keyword behaves unlike most other programming languages. It can be used in any function.
+In JavaScript, keyword `this` behaves unlike most other programming languages. It can be used in any function.
 
-There's no syntax error in the code like that:
+There's no syntax error in the following example:
 
 ```js
 function sayHi() {
@@ -220,13 +220,13 @@ In this case `this` is `undefined` in strict mode. If we try to access `this.nam
 
 In non-strict mode the value of `this` in such case will be the *global object* (`window` in a browser, we'll get to it later in the chapter [](info:global-object)). This is a historical behavior that `"use strict"` fixes.
 
-Usually such call is an programming error. If there's `this` inside a function, it expects to be called in an object context.
+Usually such call is a programming error. If there's `this` inside a function, it expects to be called in an object context.
 ````
 
 ```smart header="The consequences of unbound `this`"
 If you come from another programming language, then you are probably used to the idea of a "bound `this`", where methods defined in an object always have `this` referencing that object.
 
-In JavaScript `this` is "free", its value is evaluated at call-time and does not depend on where the method was declared, but rather on what's the object "before the dot".
+In JavaScript `this` is "free", its value is evaluated at call-time and does not depend on where the method was declared, but rather on what object is "before the dot".
 
 The concept of run-time evaluated `this` has both pluses and minuses. On the one hand, a function can be reused for different objects. On the other hand, greater flexibility opens a place for mistakes.
 

1-js/05-data-types/01-primitives-methods/article.md

@@ -50,7 +50,7 @@ The solution looks a little bit awkward, but here it is:
 
 The "object wrappers" are different for each primitive type and are called: `String`, `Number`, `Boolean` and `Symbol`. Thus, they provide different sets of methods.
 
-For instance, there exists a method [str.toUpperCase()](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase) that returns a capitalized string.
+For instance, there exists a string method [str.toUpperCase()](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase) that returns a capitalized `str`.
 
 Here's how it works:
 

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

@@ -50,7 +50,7 @@ let guestList = "Guests: // Error: Unexpected token ILLEGAL
 
 Single and double quotes come from ancient times of language creation when the need for multiline strings was not taken into account. Backticks appeared much later and thus are more versatile.
 
-Backticks also allow us to specify a "template function" before the first backtick. The syntax is: <code>func&#96;string&#96;</code>. The function `func` is called automatically, receives the string and embedded expressions and can process them. You can read more about it in the [docs](mdn:/JavaScript/Reference/Template_literals#Tagged_template_literals). This is called "tagged templates". This feature makes it easier to wrap strings into custom templating or other functionality, but it is rarely used.
+Backticks also allow us to specify a "template function" before the first backtick. The syntax is: <code>func&#96;string&#96;</code>. The function `func` is called automatically, receives the string and embedded expressions and can process them. You can read more about it in the [docs](mdn:/JavaScript/Reference/Template_literals#Tagged_templates). This is called "tagged templates". This feature makes it easier to wrap strings into custom templating or other functionality, but it is rarely used.
 
 ## Special characters
 

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

@@ -655,31 +655,37 @@ arr.map(func, thisArg);
 
 The value of `thisArg` parameter becomes `this` for `func`.
 
-For instance, here we use an object method as a filter and `thisArg` helps with that:
+For example, here we use a method of `army` object as a filter, and `thisArg` passes the context:
 
 ```js run
-let user = {
-  age: 18,
-  younger(otherUser) {
-    return otherUser.age < this.age;
+let army = {
+  minAge: 18,
+  maxAge: 27,
+  canJoin(user) {
+    return user.age >= this.minAge && user.age < this.maxAge;
   }
 };
 
 let users = [
-  {age: 12},
   {age: 16},
-  {age: 32}
+  {age: 20},
+  {age: 23},
+  {age: 30}
 ];
 
 *!*
-// find all users younger than user
-let youngerUsers = users.filter(user.younger, user);
+// find users, for who army.canJoin returns true
+let soldiers = users.filter(army.canJoin, army);
 */!*
 
-alert(youngerUsers.length); // 2
+alert(soldiers.length); // 2
+alert(soldiers[0].age); // 20
+alert(soldiers[1].age); // 23
 ```
 
-In the call above, we use `user.younger` as a filter and also provide `user` as the context for it. If we didn't provide the context, `users.filter(user.younger)` would call `user.younger` as a standalone function, with `this=undefined`. That would mean an instant error.
+If in the example above we used `users.filter(army.canJoin)`, then `army.canJoin` would be called as a standalone function, with `this=undefined`, thus leading to an instant error.
+
+A call to `users.filter(army.canJoin, army)` can be replaced with `users.filter(user => army.canJoin(user))`, that does the same. The former is used more often, as it's a bit easier to understand for most people.
 
 ## Summary
 

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

@@ -403,7 +403,7 @@ alert(item1);  // Cake
 alert(item2);  // Donut
 ```
 
-The whole `options` object except `extra` that was not mentioned, is assigned to corresponding variables:
+All properties of `options` object except `extra` that is absent in the left part, are assigned to corresponding variables:
 
 ![](destructuring-complex.svg)
 

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

@@ -4,8 +4,8 @@ We may decide to execute a function not right now, but at a certain time later.
 
 There are two methods for it:
 
-- `setTimeout` allows to run a function once after the interval of time.
-- `setInterval` allows to run a function regularly with the interval between the runs.
+- `setTimeout` allows us to run a function once after the interval of time.
+- `setInterval` allows us to run a function repeatedly, starting after the interval of time, then repeating continuously at that interval.
 
 These methods are not a part of JavaScript specification. But most environments have the internal scheduler and provide these methods. In particular, they are supported in all browsers and Node.js.
 
@@ -239,9 +239,9 @@ There's a side-effect. A function references the outer lexical environment, so,
 
 There's a special use case: `setTimeout(func, 0)`, or just `setTimeout(func)`.
 
-This schedules the execution of `func` as soon as possible. But scheduler will invoke it only after the current code is complete.
+This schedules the execution of `func` as soon as possible. But the scheduler will invoke it only after the currently executing script is complete.
 
-So the function is scheduled to run "right after" the current code.
+So the function is scheduled to run "right after" the current script.
 
 For instance, this outputs "Hello", then immediately "World":
 
@@ -251,7 +251,7 @@ setTimeout(() => alert("World"));
 alert("Hello");
 ```
 
-The first line "puts the call into calendar after 0ms". But the scheduler will only "check the calendar" after the current code is complete, so `"Hello"` is first, and `"World"` -- after it.
+The first line "puts the call into calendar after 0ms". But the scheduler will only "check the calendar" after the current script is complete, so `"Hello"` is first, and `"World"` -- after it.
 
 There are also advanced browser-related use cases of zero-delay timeout, that we'll discuss in the chapter <info:event-loop>.
 
@@ -286,10 +286,10 @@ For server-side JavaScript, that limitation does not exist, and there exist othe
 
 ## Summary
 
-- Methods `setInterval(func, delay, ...args)` and `setTimeout(func, delay, ...args)` allow to run the `func` regularly/once after `delay` milliseconds.
-- To cancel the execution, we should call `clearInterval/clearTimeout` with the value returned by `setInterval/setTimeout`.
-- Nested `setTimeout` calls is a more flexible alternative to `setInterval`, allowing 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 code is complete".
+- 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.
+- 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.
 
 Please note that all scheduling methods do not *guarantee* the exact delay.

1-js/06-advanced-functions/09-call-apply-decorators/03-debounce/task.md

@@ -6,7 +6,7 @@ importance: 5
 
 The result of `debounce(f, ms)` decorator should be a wrapper that passes the call to `f` at maximum once per `ms` milliseconds.
 
-In other words, when we call a "debounced" function, it guarantees that all other future in the closest `ms` milliseconds will be ignored.
+In other words, when we call a "debounced" function, it guarantees that all future calls to the function made less than `ms` milliseconds after the previous call will be ignored.
 
 For instance:
 
@@ -21,4 +21,4 @@ setTimeout( () => f(4), 1100); // runs
 setTimeout( () => f(5), 1500); // ignored (less than 1000 ms from the last run)
 ```
 
-In practice `debounce` is useful for functions that retrieve/update something when we know that nothing new can be done in such a short period of time, so it's better not to waste resources.
+In practice `debounce` is useful for functions that retrieve/update something when we know that nothing new can be done in such a short period of time, so it's better not to waste resources.