Sync with upstream @ 4d654318

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

@@ -5,11 +5,19 @@ Această carte este un *tutorial*. Are ca obiectiv să te ajute să înveți tre
 
 ## Specificații
 
+<<<<<<< HEAD
 **Specificația ECMA-262** conține cea mai în profunzime, detaliată și formalizată informație despre JavaScript. Aceasta definește limbajul.
+=======
+[The ECMA-262 specification](https://www.ecma-international.org/publications/standards/Ecma-262.htm) contains the most in-depth, detailed and formalized information about JavaScript. It defines the language.
+>>>>>>> 4d654318ccb6d37d6cefc9b859cf111ff3c96b27
 
 Dar fiind atât de formalizată, este grea de înțeles la început. Deci dacă ai nevoie de cea mai de încredere sursă de informație despre detaliile limbajului, specificațiile sunt locul potrivit. Dar nu sunt pentru uzul obișnuit.
 
+<<<<<<< HEAD
 Ultima schiță este la <https://tc39.es/ecma262/>.
+=======
+A new specification version is released every year. In-between these releases, the latest specification draft is at <https://tc39.es/ecma262/>.
+>>>>>>> 4d654318ccb6d37d6cefc9b859cf111ff3c96b27
 
 Pentru a citi despre noile caracteristici avansate, incluzând acelea care sunt "aproape standard" (așa-numita "etapă a treia"), vezi propunerile la <https://github.com/tc39/proposals>.
 

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

@@ -12,7 +12,7 @@ A [variable](https://en.wikipedia.org/wiki/Variable_(computer_science)) is a "na
 
 To create a variable in JavaScript, use the `let` keyword.
 
-The statement below creates (in other words: *declares* or *defines*) a variable with the name "message":
+The statement below creates (in other words: *declares*) a variable with the name "message":
 
 ```js
 let message;
@@ -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.
 

1-js/02-first-steps/06-type-conversions/1-primitive-conversions-questions/solution.md

@@ -14,6 +14,7 @@ true + false = 1
 " -9  " - 5 = -14 // (4)
 null + 1 = 1 // (5)
 undefined + 1 = NaN // (6)
+" \t \n" - 2 = -2 // (7)
 ```
 
 1. The addition with a string `"" + 1` converts `1` to a string: `"" + 1 = "1"`, and then we have `"1" + 0`, the same rule is applied.
@@ -22,3 +23,4 @@ undefined + 1 = NaN // (6)
 4. The subtraction always converts to numbers, so it makes `"  -9  "` a number `-9` (ignoring spaces around it).
 5. `null` becomes `0` after the numeric conversion.
 6. `undefined` becomes `NaN` after the numeric conversion.
+7. Space characters, are trimmed off string start and end when a string is converted to a number. Here the whole string consists of space characters, such as `\t`, `\n` and a "regular" space between them. So, similarly to an empty string, it becomes `0`.

1-js/02-first-steps/06-type-conversions/1-primitive-conversions-questions/task.md

@@ -21,6 +21,7 @@ true + false
 "  -9  " - 5
 null + 1
 undefined + 1
+" \t \n" - 2
 ```
 
 Think well, write down and then compare with the answer.

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

@@ -10,7 +10,7 @@ There are also cases when we need to explicitly convert a value to the expected
 In this chapter, we won't cover objects. Instead, we'll study primitives first. Later, after we learn about objects, we'll see how object conversion works in the chapter <info:object-toprimitive>.
 ```
 
-## ToString
+## String Conversion
 
 String conversion happens when we need the string form of a value.
 
@@ -30,7 +30,7 @@ alert(typeof value); // string
 
 String conversion is mostly obvious. A `false` becomes `"false"`, `null` becomes `"null"`, etc.
 
-## ToNumber
+## Numeric Conversion
 
 Numeric conversion happens in mathematical functions and expressions automatically.
 
@@ -94,7 +94,7 @@ alert( '1' + 2 ); // '12' (string to the left)
 This only happens when at least one of the arguments is a string. Otherwise, values are converted to numbers.
 ````
 
-## ToBoolean
+## Boolean Conversion
 
 Boolean conversion is the simplest one.
 
@@ -124,14 +124,13 @@ alert( Boolean(" ") ); // spaces, also true (any non-empty string is true)
 ```
 ````
 
-
 ## Summary
 
 The three most widely used type conversions are to string, to number, and to boolean.
 
-**`ToString`** -- Occurs when we output something. Can be performed with `String(value)`. The conversion to string is usually obvious for primitive values.
+**`String Conversion`** -- Occurs when we output something. Can be performed with `String(value)`. The conversion to string is usually obvious for primitive values.
 
-**`ToNumber`** -- Occurs in math operations. Can be performed with `Number(value)`.
+**`Numeric Conversion`** -- Occurs in math operations. Can be performed with `Number(value)`.
 
 The conversion follows the rules:
 
@@ -142,7 +141,7 @@ The conversion follows the rules:
 |<code>true&nbsp;/&nbsp;false</code> | `1 / 0` |
 | `string` | The string is read "as is", whitespaces from both sides are ignored. An empty string becomes `0`. An error gives `NaN`. |
 
-**`ToBoolean`** -- Occurs in logical operations. Can be performed with `Boolean(value)`.
+**`Boolean Conversion`** -- Occurs in logical operations. Can be performed with `Boolean(value)`.
 
 Follows the rules:
 

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

@@ -26,7 +26,7 @@ Before we move on, let's grasp some common terminology.
     alert( y - x ); // 2, binary minus subtracts values
     ```
 
-    Formally, we're talking about two different operators here: the unary negation (single operand: reverses the sign) and the binary subtraction (two operands: subtracts).
+    Formally, in the examples above we have two different operators that share the same symbol: the negation operator, a unary operator that reverses the sign, and the subtraction operator, a binary operator that subtracts one number from another.
 
 ## String concatenation, binary +
 

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

@@ -108,8 +108,8 @@ Let's examine the `for` statement part-by-part:
 |-------|----------|----------------------------------------------------------------------------|
 | begin | `i = 0`    | Executes once upon entering the loop.                                      |
 | condition | `i < 3`| Checked before every loop iteration. If false, the loop stops.              |
-| step| `i++`      | Executes after the body on each iteration but before the condition check. |
 | body | `alert(i)`| Runs again and again while the condition is truthy.                         |
+| step| `i++`      | Executes after the body on each iteration. |
 
 The general loop algorithm works like this:
 
@@ -300,7 +300,7 @@ This is just another reason not to use the question mark operator `?` instead of
 
 Sometimes we need to break out from multiple nested loops at once.
 
-For example, in the code below we loop over `i` and `j`, prompting for the coordinates `(i, j)` from `(0,0)` to `(3,3)`:
+For example, in the code below we loop over `i` and `j`, prompting for the coordinates `(i, j)` from `(0,0)` to `(2,2)`:
 
 ```js run no-beautify
 for (let i = 0; i < 3; i++) {

1-js/02-first-steps/16-javascript-specials/article.md

@@ -149,7 +149,7 @@ Conditional
 : The only operator with three parameters: `cond ? resultA : resultB`. If `cond` is truthy, returns `resultA`, otherwise `resultB`.
 
 Logical operators
-: Logical AND `&&` and OR `||` perform short-circuit evaluation and then return the value where it stopped. Logical NOT `!` converts the operand to boolean type and returns the inverse value.
+: Logical AND `&&` and OR `||` perform short-circuit evaluation and then return the value where it stopped (not necessary `true`/`false`). Logical NOT `!` converts the operand to boolean type and returns the inverse value.
 
 Comparisons
 : Equality check `==` for values of different types converts them to a number (except `null` and `undefined` that equal each other and nothing else), so these are equal:

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

@@ -2,7 +2,7 @@
 
 Before writing more complex code, let's talk about debugging.
 
-[Debugging](https://en.wikipedia.org/wiki/Debugging) is the process of finding and fixing errors within a script. All modern browsers and most other environments support debugging tools -- a special UI in developer tools that enable debugging much easier. It also allows to trace the code step by step to see what exactly is going on.
+[Debugging](https://en.wikipedia.org/wiki/Debugging) is the process of finding and fixing errors within a script. All modern browsers and most other environments support debugging tools -- a special UI in developer tools that makes debugging much easier. It also allows to trace the code step by step to see what exactly is going on.
 
 We'll be using Chrome here, because it has enough features, most other browsers have a similar process`.
 

1-js/03-code-quality/02-coding-style/article.md

@@ -26,7 +26,7 @@ let n = prompt("n?", "");
 
 if (n < 0) {
   alert(`Power ${n} is not supported,
-    please enter an integer number, greater than 0`);
+    please enter a non-negative integer number`);
 } else {
   alert( pow(x, n) );
 }

1-js/03-code-quality/03-comments/article.md

@@ -183,7 +183,12 @@ Comentariile bune ne permit să păstrăm codul organizat, să ne întoarcem la
 
 **Evită comentariile pentru:**
 
+<<<<<<< HEAD
 - Pentru a descrie "cum funcționează codul" și "ce face".
 - Folosește-le doar dacă este imposibil să faci codul atât de simplu și autodescriptiv încât comentariile să nu mai fie necesare.
+=======
+- That tell "how code works" and "what it does".
+- Put them in only if it's impossible to make the code so simple and self-descriptive that it doesn't require them.
+>>>>>>> 4d654318ccb6d37d6cefc9b859cf111ff3c96b27
 
 Comentariile sunt de asemenea folosite pentru unelte de autodocumentare precum JSDoc3: acestea le citesc și generează documentații HTML (sau documentații în alt format).

1-js/03-code-quality/05-testing-mocha/article.md

@@ -1,4 +1,4 @@
-# Automated testing with mocha
+# Automated testing with Mocha
 
 Automated testing will be used in further tasks, and it's also widely used in real projects.
 

1-js/03-code-quality/06-polyfills/article.md

@@ -19,7 +19,7 @@ Here Babel comes to the rescue.
 
 Actually, there are two parts in Babel:
 
-1. First, the transpiler program, which rewrites the code. The developer runs it on their own computer. It rewrites the code into the older standard. And then the code is delivered to the website for users. Modern project build system like [webpack](http://webpack.github.io/) provide means to run transpiler automatically on every code change, so that very easy to integrate into development process.
+1. First, the transpiler program, which rewrites the code. The developer runs it on their own computer. It rewrites the code into the older standard. And then the code is delivered to the website for users. Modern project build systems like [webpack](http://webpack.github.io/) provide means to run transpiler automatically on every code change, so that very easy to integrate into development process.
 
 2. Second, the polyfill.
 

1-js/04-object-basics/03-symbol/article.md

@@ -50,7 +50,7 @@ alert(id); // TypeError: Cannot convert a Symbol value to a string
 */!*
 ```
 
-That's a "language guard" against messing up, because strings and symbols are fundamentally different and should not occasionally convert one into another.
+That's a "language guard" against messing up, because strings and symbols are fundamentally different and should not accidentally convert one into another.
 
 If we really want to show a symbol, we need to explicitly call `.toString()` on it, like here:
 ```js run
@@ -72,7 +72,7 @@ alert(id.description); // id
 
 ## "Hidden" properties
 
-Symbols allow us to create "hidden" properties of an object, that no other part of code can occasionally access or overwrite.
+Symbols allow us to create "hidden" properties of an object, that no other part of code can accidentally access or overwrite.
 
 For instance, if we're working with `user` objects, that belong to a third-party code. We'd like to add identifiers to them.
 
@@ -92,7 +92,7 @@ alert( user[id] ); // we can access the data using the symbol as the key
 
 What's the benefit of using `Symbol("id")` over a string `"id"`?
 
-As `user` objects belongs to another code, and that code also works with them, we shouldn't just add any fields to it. That's unsafe. But a symbol cannot be accessed occasionally, the third-party code probably won't even see it, so it's probably all right to do.
+As `user` objects belongs to another code, and that code also works with them, we shouldn't just add any fields to it. That's unsafe. But a symbol cannot be accessed accidentally, the third-party code probably won't even see it, so it's probably all right to do.
 
 Also, imagine that another script wants to have its own identifier inside `user`, for its own purposes. That may be another JavaScript library, so that the scripts are completely unaware of each other.
 
@@ -284,7 +284,7 @@ Symbols are always different values, even if they have the same name. If we want
 Symbols have two main use cases:
 
 1. "Hidden" object properties.
-    If we want to add a property into an object that "belongs" to another script or a library, we can create a symbol and use it as a property key. A symbolic property does not appear in `for..in`, so it won't be occasionally processed together with other properties. Also it won't be accessed directly, because another script does not have our symbol. So the property will be protected from occasional use or overwrite.
+    If we want to add a property into an object that "belongs" to another script or a library, we can create a symbol and use it as a property key. A symbolic property does not appear in `for..in`, so it won't be accidentally processed together with other properties. Also it won't be accessed directly, because another script does not have our symbol. So the property will be protected from accidental use or overwrite.
 
     So we can "covertly" hide something into objects that we need, but others should not see, using symbolic properties.
 

1-js/04-object-basics/04-object-methods/2-check-syntax/solution.md

@@ -11,7 +11,7 @@ let user = {
 (user.go)() // error!
 ```
 
-The error message in most browsers does not give understanding what went wrong.
+The error message in most browsers does not give us much of a clue about what went wrong.
 
 **The error appears because a semicolon is missing after `user = {...}`.**
 

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

@@ -61,7 +61,7 @@ user.sayHi(); // Hello!
 ```
 
 ```smart header="Object-oriented programming"
-When we write our code using objects to represent entities, that's called an [object-oriented programming](https://en.wikipedia.org/wiki/Object-oriented_programming), in short: "OOP".
+When we write our code using objects to represent entities, that's called [object-oriented programming](https://en.wikipedia.org/wiki/Object-oriented_programming), in short: "OOP".
 
 OOP is a big thing, an interesting science of its own. How to choose the right entities? How to organize the interaction between them? That's architecture, and there are great books on that topic, like "Design Patterns: Elements of Reusable Object-Oriented Software" by E.Gamma, R.Helm, R.Johnson, J.Vissides or "Object-Oriented Analysis and Design with Applications" by G.Booch, and more.
 ```
@@ -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,17 +220,17 @@ 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.
+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, the greater flexibility creates more possibilities for mistakes.
 
-Here our position is not to judge whether this language design decision is good or bad. We'll understand how to work with it, how to get benefits and evade problems.
+Here our position is not to judge whether this language design decision is good or bad. We'll understand how to work with it, how to get benefits and avoid problems.
 ```
 
 ## Internals: Reference Type

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

@@ -196,7 +196,7 @@ For instance:
       }
     };
 
-    alert(obj + 2); // 22 (ToPrimitive returned string => concatenation)
+    alert(obj + 2); // 22 (conversion to primitive returned a string => concatenation)
     ```
 
 ## Summary

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

@@ -27,7 +27,7 @@ alert(user.name); // Jack
 alert(user.isAdmin); // false
 ```
 
-When a function is executed as `new User(...)`, it does the following steps:
+When a function is executed with `new`, it does the following steps:
 
 1. A new empty object is created and assigned to `this`.
 2. The function body executes. Usually it modifies `this`, adds new properties to it.
@@ -51,7 +51,7 @@ function User(name) {
 }
 ```
 
-So the result of `new User("Jack")` is the same object as:
+So `let user = new User("Jack")` gives the same result as:
 
 ```js
 let user = {
@@ -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.
@@ -148,10 +148,10 @@ function BigUser() {
 
   this.name = "John";
 
-  return { name: "Godzilla" };  // <-- returns an object
+  return { name: "Godzilla" };  // <-- returns this object
 }
 
-alert( new BigUser().name );  // Godzilla, got that object ^^
+alert( new BigUser().name );  // Godzilla, got that object
 ```
 
 And here's an example with an empty `return` (or we could place a primitive after it, doesn't matter):
@@ -161,10 +161,7 @@ function SmallUser() {
 
   this.name = "John";
 
-  return; // finishes the execution, returns this
-
-  // ...
-
+  return; // <-- returns this
 }
 
 alert( new SmallUser().name );  // John