Merge branch 'master' into polyfills--transpilers

Author: odsantos

1-js/01-getting-started/1-intro/article.md

@@ -26,7 +26,7 @@ Interpretadores diferentes têm "codinomes" diferentes. Por exemplo:
 
 - [V8](https://en.wikipedia.org/wiki/V8_(JavaScript_engine)) -- no Chrome e no Opera.
 - [SpiderMonkey](https://en.wikipedia.org/wiki/SpiderMonkey) -- no Firefox.
-- ...Há outros codinomes como "Chakra" para o IE, "ChakraCore" para Microsoft Edge, "Nitro" e "SquirrelFish" para Safari, etc.
+- ...Há outros codinomes como "Chakra" para o IE, "JavaScriptCore", "Nitro" e "SquirrelFish" para Safari, etc.
 
 Os termos acima são bons para lembrar, pois são usados em artigos de desenvolvedores na internet. Vamos usá-los também. Por exemplo, se "um recurso X é suportado pelo V8", então ele provavelmente funciona no Chrome e no Opera.
 

1-js/02-first-steps/02-structure/article.md

@@ -46,7 +46,7 @@ alert(3 +
 + 2);
 ```
 
-O código produz `6` porque o Javascript não insere pontos e virgulas aqui. É intuitivamente óbvio que se a linha termina com um sinal de mais `"+"`, então é uma "expressão incompleta", logo o ponto e vírgula não é necessário. E neste caso isso funciona como pretendido.
+O código produz `6` porque o Javascript não insere pontos e virgulas aqui. É intuitivamente óbvio que se a linha termina com um sinal de mais `"+"`, então é uma "expressão incompleta", logo o ponto e vírgula aí seria incorreto. E neste caso isso funciona como pretendido.
 
 **Mas há situações em que o JavaScript "falha" em assumir um ponto e vírgula onde ele é realmente necessário.**
 
@@ -56,40 +56,36 @@ Erros que ocorrem em tais casos são bastante difíceis de encontrar e corrigir.
 Se você está curioso para ver um exemplo concreto de tal erro, verifique este código:
 
 ```js run
-[1, 2].forEach(alert)
+alert("Hello");
+
+[1, 2].forEach(alert);
 ```
 
-Não há necessidade de pensar sobre o significado dos parênteses `[]` e `forEach` ainda. Nós vamos estudá-los mais tarde. Por enquanto, apenas lembre-se que o resultado do código: mostra `1` e depois` 2`.
+Não há necessidade de pensar sobre o significado dos parênteses `[]` e também do `forEach`. Nós vamos estudá-los mais tarde. Por enquanto, apenas lembre-se do resultado da execução do código: ele mostra `Hello`, depois `1`, e depois` 2`.
 
-Agora, vamos adicionar um `alert` antes do código e * não * terminá-lo com um ponto e vírgula:
+Agora, vamos remover o ponto e vírgula depois do `alert`:
 
 ```js run no-beautify
-alert("Haverá um erro")
+alert("Hello")
 
-[1, 2].forEach(alert)
+[1, 2].forEach(alert);
 ```
 
-Agora, se nós executarmos o código, apenas o primeiro `alert` é mostrado e então temos um erro!
-
-Mas tudo está bem novamente se adicionarmos um ponto e vírgula após `alert`:
-```js run
-alert("Tudo bem agora");
+A diferença em comparação com o código acima é de apenas um caractere: o ponto e vírgula da primeira linha se foi.
 
-[1, 2].forEach(alert)  
-```
+Se nós executarmos esse código, apenas o primeiro `Hello` é mostrado (e então há um erro, você pode precisar de abrir a consola para o ver). Já não existem mais números.
 
-Agora temos a mensagem "Tudo bem agora" seguida por "1" e "2".
+Isso ocorre porque o JavaScript não assume um ponto e vírgula antes dos colchetes `[...]`. Portanto, o código no último exemplo é tratado como uma única instrução. 
 
-
-O erro na variante sem ponto e vírgula ocorre porque o JavaScript não assume um ponto e vírgula antes dos colchetes `[...]`.
-
-Portanto, como o ponto e vírgula não é inserido automaticamente, o código no primeiro exemplo é tratado como uma única instrução. Veja como o mecanismo vê isso:
+Veja como o mecanismo vê isso:
 
 ```js run no-beautify
-alert("Haverá um erro")[1, 2].forEach(alert)
+alert("Hello")[1, 2].forEach(alert);
 ```
 
-Mas devem ser duas declarações separadas, não uma. Tal fusão neste caso é completamente errado, daí o erro. Isso pode acontecer em outras situações.
+Parece estranho, não? Tal fusão neste caso é completamente errada. Nós precisamos de colocar um ponto e vírgula depois de `alert` para o código funcionar corretamente.
+
+Isso também pode acontecer em outras situações.
 ````
 
 Recomendamos colocar ponto e vírgula entre as frases, mesmo que estejam separadas por novas linhas. Esta regra é amplamente adotada pela comunidade. Vamos notar mais uma vez -- *é possível* deixar de fora os pontos e vírgulas na maior parte do tempo. Mas é mais seguro -- especialmente para um iniciante -- usá-los.

1-js/02-first-steps/05-types/article.md

@@ -64,7 +64,7 @@ Os valores numéricos especiais pertencem formalmente ao tipo "número". Claro q
 
 Veremos mais sobre como trabalhar com números no capítulo <info:number>.
 
-## BigInt
+## BigInt [#bigint-type]
 
 In JavaScript, the "number" type cannot represent integer values larger than <code>(2<sup>53</sup>-1)</code> (that's `9007199254740991`), or less than <code>-(2<sup>53</sup>-1)</code> for negatives. It's a technical limitation caused by their internal representation.
 

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

@@ -56,17 +56,21 @@ alert( 8 % 3 ); // 2, a remainder of 8 divided by 3
 
 ### Exponentiation **
 
-The exponentiation operator `a ** b` multiplies `a` by itself `b` times.
+The exponentiation operator `a ** b` raises `a` to the power of `b`.
+
+In school maths, we write that as a<sup>b</sup>.
 
 For instance:
 
 ```js run
-alert( 2 ** 2 ); // 4  (2 multiplied by itself 2 times)
-alert( 2 ** 3 ); // 8  (2 * 2 * 2, 3 times)
-alert( 2 ** 4 ); // 16 (2 * 2 * 2 * 2, 4 times)
+alert( 2 ** 2 ); // 2² = 4
+alert( 2 ** 3 ); // 2³ = 8
+alert( 2 ** 4 ); // 2⁴ = 16
 ```
 
-Mathematically, the exponentiation is defined for non-integer numbers as well. For example, a square root is an exponentiation by `1/2`:
+Just like in maths, the exponentiation operator is defined for non-integer numbers as well. 
+
+For example, a square root is an exponentiation by ½:
 
 ```js run
 alert( 4 ** (1/2) ); // 2 (power of 1/2 is the same as a square root)

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

@@ -368,9 +368,18 @@ break label; // jump to the label below (doesn't work)
 label: for (...)
 ```
 
-A call to `continue` is only possible from inside the loop.
+A `break` directive must be inside a code block. Technically, any labelled code block will do, e.g.:
+```js
+label: {
+  // ...
+  break label; // works
+  // ...
+}
+```
+
+...Although, 99.9% of the time `break` used is inside loops, as we've seen in the examples above.
 
-The `break` directive may be placed before code blocks too, as `label: { ... }`, but it's almost never used like that. And it also works only inside-out.
+A `continue` is only possible from inside a loop.
 ````
 
 ## Summary

1-js/02-first-steps/15-function-basics/2-rewrite-function-question-or/solution.md

@@ -14,4 +14,4 @@ function checkAge(age) {
 }
 ```
 
-Note that the parentheses around `age > 18` are not required here. They exist for better readabilty.
+Note that the parentheses around `age > 18` are not required here. They exist for better readability.

1-js/02-first-steps/15-function-basics/article.md

@@ -20,10 +20,10 @@ function showMessage() {
 }
 ```
 
-A palavra-chave `function` vem primeiro, depois vem o *nome da função*, e uma lista de *parâmetros* entre os parêntesis (vazio no exemplo acima) e finalmente o código da função, também chamado de "o corpo da função", entre chaves.
+A palavra-chave `function` vem primeiro, depois vem o *nome da função*, e uma lista de *parâmetros* entre os parêntesis (separados por vírgulas, vazia no exemplo acima, veremos exemplos mais tarde) e finalmente o código da função, também chamado de "o corpo da função", entre chaves.
 
 ```js
-function name(parameters) {
+function name(parameter1, parameter2, ... parameterN) {
   ...corpo...
 }
 ```
@@ -137,26 +137,23 @@ It's a good practice to minimize the use of global variables. Modern code has fe
 
 ## Parameters
 
-We can pass arbitrary data to functions using parameters (also called *function arguments*) .
+We can pass arbitrary data to functions using parameters.
 
 In the example below, the function has two parameters: `from` and `text`.
 
 ```js run
-function showMessage(*!*from, text*/!*) { // arguments: from, text
+function showMessage(*!*from, text*/!*) { // parameters: from, text
   alert(from + ': ' + text);
 }
 
-*!*
-showMessage('Ann', 'Hello!'); // Ann: Hello! (*)
-showMessage('Ann', "What's up?"); // Ann: What's up? (**)
-*/!*
+*!*showMessage('Ann', 'Hello!');*/!* // Ann: Hello! (*)
+*!*showMessage('Ann', "What's up?");*/!* // Ann: What's up? (**)
 ```
 
 When the function is called in lines `(*)` and `(**)`, the given values are copied to local variables `from` and `text`. Then the function uses them.
 
 Here's one more example: we have a variable `from` and pass it to the function. Please note: the function changes `from`, but the change is not seen outside, because a function always gets a copy of the value:
 
-
 ```js run
 function showMessage(from, text) {
 
@@ -175,19 +172,31 @@ showMessage(from, "Hello"); // *Ann*: Hello
 alert( from ); // Ann
 ```
 
+When a value is passed as a function parameter, it's also called an *argument*.
+
+In other words, to put these terms straight:
+
+- A parameter is the variable listed inside the parentheses in the function declaration (it's a declaration time term)
+- An argument is the value that is passed to the function when it is called (it's a call time term).
+
+We declare functions listing their parameters, then call them passing arguments.
+
+In the example above, one might say: "the function `sayMessage` is declared with two parameters, then called with two arguments: `from` and `"Hello"`".
+
+
 ## Default values
 
-If a parameter is not provided, then its value becomes `undefined`.
+If a function is called, but an argument is not provided, then the corresponding value becomes `undefined`.
 
 For instance, the aforementioned function `showMessage(from, text)` can be called with a single argument:
 
 ```js
 showMessage("Ann");
 ```
 
-That's not an error. Such a call would output `"Ann: undefined"`. There's no `text`, so it's assumed that `text === undefined`.
+That's not an error. Such a call would output `"*Ann*: undefined"`. As the value for `text` isn't passed, it becomes `undefined`.
 
-If we want to use a "default" `text` in this case, then we can specify it after `=`:
+We can specify the so-called "default" (to use if omitted) value for a parameter in the function declaration, using `=`:
 
 ```js run
 function showMessage(from, *!*text = "no text given"*/!*) {
@@ -211,19 +220,23 @@ function showMessage(from, text = anotherFunction()) {
 ```smart header="Evaluation of default parameters"
 In JavaScript, a default parameter is evaluated every time the function is called without the respective parameter.
 
-In the example above, `anotherFunction()` is called every time `showMessage()` is called without the `text` parameter.
+In the example above, `anotherFunction()` isn't called at all, if the `text` parameter is provided.
+
+On the other hand, it's independently called every time when `text` is missing.
 ```
 
 ### Alternative default parameters
 
-Sometimes it makes sense to set default values for parameters not in the function declaration, but at a later stage, during its execution.
+Sometimes it makes sense to assign default values for parameters not in the function declaration, but at a later stage.
 
-To check for an omitted parameter, we can compare it with `undefined`:
+We can check if the parameter is passed during the function execution, by comparing it with `undefined`:
 
 ```js run
 function showMessage(text) {
+  // ...
+
 *!*
-  if (text === undefined) {
+  if (text === undefined) { // if the parameter is missing
     text = 'empty message';
   }
 */!*
@@ -234,21 +247,21 @@ function showMessage(text) {
 showMessage(); // empty message
 ```
 
-...Or we could use the `||` operator:
+...Or we could use the `??` operator:
 
 ```js
-// if text parameter is omitted or "" is passed, set it to 'empty'
 function showMessage(text) {
+  // if text is undefined or otherwise falsy, set it to 'empty'
   text = text || 'empty';
   ...
 }
 ```
 
-Modern JavaScript engines support the [nullish coalescing operator](info:nullish-coalescing-operator) `??`, it's better when falsy values, such as `0`, are considered regular:
+Modern JavaScript engines support the [nullish coalescing operator](info:nullish-coalescing-operator) `??`, it's better when most falsy values, such as `0`, should be considered "normal":
 
 ```js run
-// if there's no "count" parameter, show "unknown"
 function showCount(count) {
+  // if count is undefined or null, show "unknown"
   alert(count ?? "unknown");
 }
 
@@ -411,7 +424,7 @@ Functions that are used *very often* sometimes have ultrashort names.
 
 For example, the [jQuery](http://jquery.com) framework defines a function with `$`. The [Lodash](http://lodash.com/) library has its core function named `_`.
 
-These are exceptions. Generally functions names should be concise and descriptive.
+These are exceptions. Generally function names should be concise and descriptive.
 ```
 
 ## Functions == Comments

1-js/02-first-steps/17-arrow-functions-basics/1-rewrite-arrow/solution.md

@@ -1,7 +1,7 @@
 
 ```js run
 function ask(question, yes, no) {
-  if (confirm(question)) yes()
+  if (confirm(question)) yes();
   else no();
 }
 

1-js/02-first-steps/17-arrow-functions-basics/1-rewrite-arrow/task.md

@@ -5,7 +5,7 @@ Replace Function Expressions with arrow functions in the code below:
 
 ```js run
 function ask(question, yes, no) {
-  if (confirm(question)) yes()
+  if (confirm(question)) yes();
   else no();
 }
 

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

@@ -1,4 +1,4 @@
-# Depuração de erros no Chrome
+# Depuração de erros no navegador
 
 Antes de escrevermos código mais complexo, vamos falar de debugging (depuração de erros).