Resolve conflicts

Author: odsantos

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

@@ -13,33 +13,17 @@ Uma nova versão dessa especificação é lançada todos os anos. Entre estes la
 
 Para ler sobre as mais novas funcionalidades (*bleeding-edge features*), incluindo as que estão em fase de padronização (chamadas também de "estágio 3"), veja as suas propostas em <https://github.com/tc39/proposals>.
 
-<<<<<<< HEAD
 E mais, se você está desenvolvendo para browsers, há outras especificações que cobrem esta demanda na [segunda parte](info:browser-environment) do tutorial.
-=======
-Also, if you're in developing for the browser, then there are other specifications covered in the [second part](info:browser-environment) of the tutorial.
->>>>>>> 3a0b3f4e31d4c4bbe90ed4c9c6e676a888ad8311
 
 ## Manuais
 
-<<<<<<< HEAD
-- **MDN (Mozilla) JavaScript Reference**  é um manual com exemplos e outras informações. É ótimo para um entendimento sobre funções, métodos da linguagem, etc.
-=======
-- **MDN (Mozilla) JavaScript Reference** is the main manual with examples and other information. It's great to get in-depth information about individual language functions, methods etc.
->>>>>>> 3a0b3f4e31d4c4bbe90ed4c9c6e676a888ad8311
+- **MDN (Mozilla) JavaScript Reference**  é um manual com exemplos e outras informações. É ótimo para um entendimento sobre funções da linguagem, métodos , etc.
 
 	Pode ser encontrado em <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference>.
 
-<<<<<<< HEAD
 	Porém, às vezes é melhor fazer uma busca na internet. Apenas use "MDN [termo]" na busca, por exemplo: <https://google.com/search?q=MDN+parseInt> para procurar pela função `parseInt`.
 
-- **MSDN** - Manual da Microsoft com muitas informações, incluindo JavaScript (frequentemente referido como JScript). Se precisar de algo específico para o Internet Explorer, é melhor ir por aqui: <http://msdn.microsoft.com/>.
-
-	Assim como para o manual da Mozilla, também podemos fazer uma busca na internet com frases do tipo "RegExp MSDN" ou "RegExp MSDN jscript".
-
 ## Tabelas de compatibilidade
-=======
-Although, it's often best to use an internet search instead. Just use "MDN [term]" in the query, e.g. <https://google.com/search?q=MDN+parseInt> to search for `parseInt` function.
->>>>>>> 3a0b3f4e31d4c4bbe90ed4c9c6e676a888ad8311
 
 JavaScript é uma linguagem em desenvolvimento, novas funcionalidades são adicionadas regularmente.
 

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

@@ -115,11 +115,7 @@ Existem dois tipos de indentação:
 
     Uma vantagem dos espaços sobre *tabs*, é que espaços permitem configurações de indentação mais flexíveis do que o símbolo "Tab".
 
-<<<<<<< HEAD
     Por exemplo, podemos alinhar os argumentos com o parêntese de abertura, desta forma:
-=======
-    For instance, we can align the parameters with the opening bracket, like this:
->>>>>>> 3a0b3f4e31d4c4bbe90ed4c9c6e676a888ad8311
 
     ```js no-beautify
     show(parameters,

1-js/04-object-basics/03-garbage-collection/article.md

@@ -207,6 +207,6 @@ A general book "The Garbage Collection Handbook: The Art of Automatic Memory Man
 
 If you are familiar with low-level programming, the more detailed information about V8 garbage collector is in the article [A tour of V8: Garbage Collection](http://jayconrod.com/posts/55/a-tour-of-v8-garbage-collection).
 
-[V8 blog](http://v8project.blogspot.com/) also publishes articles about changes in memory management from time to time. Naturally, to learn the garbage collection, you'd better prepare by learning about V8 internals in general and read the blog of [Vyacheslav Egorov](http://mrale.ph) who worked as one of V8 engineers. I'm saying: "V8", because it is best covered with articles in the internet. For other engines, many approaches are similar, but garbage collection differs in many aspects.
+[V8 blog](https://v8.dev/) also publishes articles about changes in memory management from time to time. Naturally, to learn the garbage collection, you'd better prepare by learning about V8 internals in general and read the blog of [Vyacheslav Egorov](http://mrale.ph) who worked as one of V8 engineers. I'm saying: "V8", because it is best covered with articles in the internet. For other engines, many approaches are similar, but garbage collection differs in many aspects.
 
 In-depth knowledge of engines is good when you need low-level optimizations. It would be wise to plan that as the next step after you're familiar with the language.  

1-js/04-object-basics/06-constructor-new/2-calculator-constructor/_js.view/test.js

@@ -1,30 +1,31 @@
 
 describe("calculator", function() {
-  let calculator;
-  before(function() {
-    sinon.stub(window, "prompt")
-
-    prompt.onCall(0).returns("2");
-    prompt.onCall(1).returns("3");
-
-    calculator = new Calculator();
-    calculator.read();
-  });
+    let calculator;
+    before(function() {
+      sinon.stub(window, "prompt")
 
-  it("the read method asks for two values using prompt and remembers them in object properties", function() {
-    assert.equal(calculator.a, 2);
-    assert.equal(calculator.b, 3);
-  });
-
-  it("when 2 and 3 are entered, the sum is 5", function() {
-    assert.equal(calculator.sum(), 5);
-  });
-
-  it("when 2 and 3 are entered, the product is 6", function() {
-    assert.equal(calculator.mul(), 6);
-  });
-
-  after(function() {
-    prompt.restore();
+      prompt.onCall(0).returns("2");
+      prompt.onCall(1).returns("3");
+  
+      calculator = new Calculator();
+      calculator.read();
+    });
+    
+    it("the read method asks for two values using prompt and remembers them in object properties", function() {
+      assert.equal(calculator.a, 2);
+      assert.equal(calculator.b, 3);
+    });
+  
+    it("when 2 and 3 are entered, the sum is 5", function() {
+      assert.equal(calculator.sum(), 5);
+    });
+  
+    it("when 2 and 3 are entered, the product is 6", function() {
+      assert.equal(calculator.mul(), 6);
+    });
+  
+    after(function() {
+      prompt.restore();
+    });
   });
-});
+  

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

@@ -83,7 +83,7 @@ let user = new function() {
 The constructor can't be called again, because it is not saved anywhere, just created and called. So this trick aims to encapsulate the code that constructs the single object, without future reuse.
 ````
 
-## Dual-syntax constructors: new.target
+## Constructor mode test: new.target
 
 ```smart header="Advanced stuff"
 The syntax from this section is rarely used, skip it unless you want to know everything.
@@ -109,7 +109,9 @@ new User(); // function User { ... }
 */!*
 ```
 
-That can be used to allow both `new` and regular calls to work the same. That is, create the same object:
+That can be used inside the function to know whether it was called with `new`, "in constructor mode", or without it, "in regular mode".
+
+We can also make both `new` and regular calls to do the same, like this:
 
 ```js run
 function User(name) {
@@ -210,6 +212,8 @@ john = {
 */
 ```
 
+To create complex objects, there's a more advanced syntax, [classes](info:classes), that we'll cover later.
+
 ## Summary
 
 - Constructor functions or, briefly, constructors, are regular functions, but there's a common agreement to name them with capital letter first.

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

@@ -16,7 +16,7 @@ A value of this type can be created using `Symbol()`:
 let id = Symbol();
 ```
 
-We can also give symbol a description (also called a symbol name), mostly useful for debugging purposes:
+Upon creation, we can give symbol a description (also called a symbol name), mostly useful for debugging purposes:
 
 ```js
 // id is a symbol with the description "id"
@@ -94,7 +94,7 @@ 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 accidentally, the third-party code probably won't even see it, so it's probably all right to do.
 
-Imagine that another script wants to have its own "id" property inside `user`, for its own purposes. That may be another JavaScript library, so the scripts are completely unaware of each other.
+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.
 
 Then that script can create its own `Symbol("id")`, like this:
 
@@ -105,9 +105,9 @@ let id = Symbol("id");
 user[id] = "Their id value";
 ```
 
-There will be no conflict, because symbols are always different, even if they have the same name.
+There will be no conflict between our and their identifiers, because symbols are always different, even if they have the same name.
 
-Now note that if we used a string `"id"` instead of a symbol for the same purpose, then there *would* be a conflict:
+...But if we used a string `"id"` instead of a symbol for the same purpose, then there *would* be a conflict:
 
 ```js
 let user = { name: "John" };
@@ -123,7 +123,7 @@ user.id = "Their id value"
 
 ### Symbols in an object literal
 
-If we want to use a symbol in an object literal, we need square brackets.
+If we want to use a symbol in an object literal `{...}`, we need square brackets around it.
 
 Like this:
 
@@ -161,7 +161,7 @@ for (let key in user) alert(key); // name, age (no symbols)
 alert( "Direct: " + user[id] );
 ```
 
-That's a part of the general "hiding" concept. If another script or a library loops over our object, it won't unexpectedly access a symbolic property.
+`Object.keys(user)` also ignores them. That's a part of the general "hiding symbolic properties" principle. If another script or a library loops over our object, it won't unexpectedly access a symbolic property.
 
 In contrast, [Object.assign](mdn:js/Object/assign) copies both string and symbol properties:
 
@@ -180,13 +180,11 @@ There's no paradox here. That's by design. The idea is that when we clone an obj
 
 ## Global symbols
 
-As we've seen, usually all symbols are different, even if they have the same names. But sometimes we want same-named symbols to be same entities.
-
-For instance, different parts of our application want to access symbol `"id"` meaning exactly the same property.
+As we've seen, usually all symbols are different, even if they have the same name. But sometimes we want same-named symbols to be same entities. For instance, different parts of our application want to access symbol `"id"` meaning exactly the same property.
 
 To achieve that, there exists a *global symbol registry*. We can create symbols in it and access them later, and it guarantees that repeated accesses by the same name return exactly the same symbol.
 
-In order to create or read a symbol in the registry, use `Symbol.for(key)`.
+In order to read (create if absent) a symbol from the registry, use `Symbol.for(key)`.
 
 That call checks the global registry, and if there's a symbol described as `key`, then returns it, otherwise creates a new symbol `Symbol(key)` and stores it in the registry by the given `key`.
 
@@ -196,7 +194,7 @@ For instance:
 // read from the global registry
 let id = Symbol.for("id"); // if the symbol did not exist, it is created
 
-// read it again
+// read it again (maybe from another part of the code)
 let idAgain = Symbol.for("id");
 
 // the same symbol
@@ -218,22 +216,29 @@ For global symbols, not only `Symbol.for(key)` returns a symbol by name, but the
 For instance:
 
 ```js run
+// get symbol by name
 let sym = Symbol.for("name");
 let sym2 = Symbol.for("id");
 
-// get name from symbol
+// get name by symbol
 alert( Symbol.keyFor(sym) ); // name
 alert( Symbol.keyFor(sym2) ); // id
 ```
 
 The `Symbol.keyFor` internally uses the global symbol registry to look up the key for the symbol. So it doesn't work for non-global symbols. If the symbol is not global, it won't be able to find it and returns `undefined`.
 
+That said, any symbols have `description` property.
+
 For instance:
 
 ```js run
-alert( Symbol.keyFor(Symbol.for("name")) ); // name, global symbol
+let globalSymbol = Symbol.for("name");
+let localSymbol = Symbol("name");
+
+alert( Symbol.keyFor(globalSymbol) ); // name, global symbol
+alert( Symbol.keyFor(localSymbol) ); // undefined, not global
 
-alert( Symbol.keyFor(Symbol("name2")) ); // undefined, the argument isn't a global symbol
+alert( localSymbol.description ); // name
 ```
 
 ## System symbols
@@ -256,9 +261,9 @@ Other symbols will also become familiar when we study the corresponding language
 
 `Symbol` is a primitive type for unique identifiers.
 
-Symbols are created with `Symbol()` call with an optional description.
+Symbols are created with `Symbol()` call with an optional description (name).
 
-Symbols are always different values, even if they have the same name. If we want same-named symbols to be equal, then we should use the global registry: `Symbol.for(key)` returns (creates if needed) a global symbol with `key` as the name. Multiple calls of `Symbol.for` return exactly the same symbol.
+Symbols are always different values, even if they have the same name. If we want same-named symbols to be equal, then we should use the global registry: `Symbol.for(key)` returns (creates if needed) a global symbol with `key` as the name. Multiple calls of `Symbol.for` with the same `key` return exactly the same symbol.
 
 Symbols have two main use cases:
 
@@ -269,4 +274,4 @@ Symbols have two main use cases:
 
 2. There are many system symbols used by JavaScript which are accessible as `Symbol.*`. We can use them to alter some built-in behaviors. For instance, later in the tutorial we'll use `Symbol.iterator` for [iterables](info:iterable), `Symbol.toPrimitive` to setup [object-to-primitive conversion](info:object-toprimitive) and so on.
 
-Technically, symbols are not 100% hidden. There is a built-in method [Object.getOwnPropertySymbols(obj)](mdn:js/Object/getOwnPropertySymbols) that allows us to get all symbols. Also there is a method named [Reflect.ownKeys(obj)](mdn:js/Reflect/ownKeys) that returns *all* keys of an object including symbolic ones. So they are not really hidden. But most libraries, built-in methods and syntax constructs adhere to a common agreement that they are. And the one who explicitly calls the aforementioned methods probably understands well what he's doing.
+Technically, symbols are not 100% hidden. There is a built-in method [Object.getOwnPropertySymbols(obj)](mdn:js/Object/getOwnPropertySymbols) that allows us to get all symbols. Also there is a method named [Reflect.ownKeys(obj)](mdn:js/Reflect/ownKeys) that returns *all* keys of an object including symbolic ones. So they are not really hidden. But most libraries, built-in functions and syntax constructs don't use these methods.

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

@@ -12,7 +12,7 @@ async function f() {
 }
 ```
 
-The word "async" before a function means one simple thing: a function always returns a promise. Even If a function actually returns a non-promise value, prepending the function definition with the "async" keyword directs JavaScript to automatically wrap that value in a resolved promise.
+The word "async" before a function means one simple thing: a function always returns a promise. Other values are wrapped in a resolved promise automatically.
 
 For instance, this function returns a resolved promise with the result of `1`; let's test it:
 
@@ -172,7 +172,7 @@ f();
 If `await` gets a non-promise object with `.then`, it calls that method providing the built-in functions `resolve` and `reject` as arguments (just as it does for a regular `Promise` executor). Then `await` waits until one of them is called (in the example above it happens in the line `(*)`) and then proceeds with the result.
 ````
 
-````smart header="Async methods"
+````smart header="Async class methods"
 To declare an async class method, just prepend it with `async`:
 
 ```js run
@@ -215,7 +215,7 @@ async function f() {
 }
 ```
 
-In real situations, the promise may take some time before it rejects. So `await` will wait, and then throw an error.
+In real situations, the promise may take some time before it rejects. In that case there will be a delay before `await` throws an error.
 
 We can catch that error using `try..catch`, the same way as a regular `throw`:
 
@@ -289,34 +289,6 @@ In the case of an error, it propagates as usual, from the failed promise to `Pro
 
 ````
 
-## Microtask queue [#microtask-queue]
-
-As we've seen in the chapter <info:microtask-queue>, promise handlers are executed asynchronously. Every `.then/catch/finally` handler first gets into the "microtask queue" and executed after the current code is complete.
-
-`Async/await` is based on promises, so it uses the same microtask queue internally, and has the similar priority over macrotasks.
-
-For instance, we have:
-- `setTimeout(handler, 0)`, that should run `handler` with zero delay.
-- `let x = await f()`, function `f()` is async, but returns immediately.
-
-Which one runs first if `await` is *below* `setTimeout` in the code?
-
-```js run
-async function f() {
-  return 1;
-}
-
-(async () => {
-    setTimeout(() => alert('timeout'), 0);
-
-    await f();
-
-    alert('await');
-})();
-```
-
-There's no ambiguity here: `await` always finishes first, because (as a microtask) it has a higher priority than `setTimeout` handling.
-
 ## Summary
 
 The `async` keyword before a function has two effects:

2-ui/4-forms-controls/1-form-elements/article.md

@@ -2,13 +2,13 @@
 
 Forms and control elements, such as `<input>` have a lot of special properties and events.
 
-Working with forms can be much more convenient if we know them.
+Working with forms will be much more convenient when we learn them.
 
 ## Navigation: form and elements
 
 Document forms are members of the special collection `document.forms`.
 
-That's a *named* collection: we can use both the name and the number to get the form.
+That's a so-called "named collection": it's both named and ordered. We can use both the name or the number in the document to get the form.
 
 ```js no-beautify
 document.forms.my - the form with name="my"
@@ -155,7 +155,7 @@ Let's talk about form controls.
 
 ### input and textarea
 
-Normally, we can access the value as `input.value` or `input.checked` for checkboxes.
+We can access their value as `input.value` (string) or `input.checked` (boolean) for checkboxes.
 
 Like this:
 
@@ -227,7 +227,7 @@ Here's an example of how to get selected values from a multi-select:
 </script>
 ```
 
-The full specification of the `<select>` element is available at <https://html.spec.whatwg.org/multipage/forms.html#the-select-element>.
+The full specification of the `<select>` element is available in the specification <https://html.spec.whatwg.org/multipage/forms.html#the-select-element>.
 
 ### new Option
 
@@ -241,7 +241,7 @@ This syntax is optional. We can use `document.createElement('option')` and set a
 
 - `text` -- the text inside the option,
 - `value` -- the option value,
-- `defaultSelected` -- if `true`, then `selected` attribute is created,
+- `defaultSelected` -- if `true`, then `selected` HTML-attribute is created,
 - `selected` -- if `true`, then the option is selected.
 
 The difference between `defaultSelected` and `selected` is that `defaultSelected` sets the HTML-attribute (that we can get using `option.getAttribute('selected')`, while `selected` sets whether the option is selected or not.