Merge pull request #214 from javascript-tutorial/sync-e01998ba

Sync with upstream @ e01998b

Author: odsantos

1-js/02-first-steps/11-logical-operators/article.md

@@ -64,7 +64,7 @@ if (hour < 10 || hour > 18 || isWeekend) {
 }
 ```
 
-## OR "||" finds the first truthy value
+## OR "||" finds the first truthy value [#or-finds-the-first-truthy-value]
 
 The logic described above is somewhat classical. Now, let's bring in the "extra" features of JavaScript.
 

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

@@ -318,7 +318,7 @@ alert('Done!');
 
 We need a way to stop the process if the user cancels the input.
 
-The ordinary `break` after `input` would only break the inner loop. That's not sufficient--labels, come to the rescue!
+The ordinary `break` after `input` would only break the inner loop. That's not sufficient -- labels, come to the rescue!
 
 A *label* is an identifier with a colon before a loop:
 ```js
@@ -363,12 +363,14 @@ Labels do not allow us to jump into an arbitrary place in the code.
 
 For example, it is impossible to do this:
 ```js
-break label; // doesn't jumps to the label below
+break label; // jump to the label below (doesn't work)
 
 label: for (...)
 ```
 
-A call to `break/continue` is only possible from inside a loop and the label must be somewhere above the directive.
+A call to `continue` is only possible from inside the loop.
+
+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.
 ````
 
 ## Summary

1-js/04-object-basics/02-object-copy/article.md

@@ -100,7 +100,7 @@ alert( a == b ); // false
 
 For comparisons like `obj1 > obj2` or for a comparison against a primitive `obj == 5`, objects are converted to primitives. We'll study how object conversions work very soon, but to tell the truth, such comparisons are needed very rarely -- usually they appear as a result of a programming mistake.
 
-## Cloning and merging, Object.assign
+## Cloning and merging, Object.assign [#cloning-and-merging-object-assign]
 
 So, copying an object variable creates one more reference to the same object.
 
@@ -186,7 +186,7 @@ let clone = Object.assign({}, user);
 
 It copies all properties of `user` into the empty object and returns it.
 
-There are also other methods of cloning an object, e.g. using the [spread operator](info:rest-parameters-spread) `clone = {...user}`, covered later in the tutorial.
+There are also other methods of cloning an object, e.g. using the [spread syntax](info:rest-parameters-spread) `clone = {...user}`, covered later in the tutorial.
 
 ## Nested cloning
 

1-js/05-data-types/02-number/article.md

@@ -160,7 +160,7 @@ There are two ways to do so:
     ```js run
     let num = 1.23456;
 
-    alert( Math.floor(num * 100) / 100 ); // 1.23456 -> 123.456 -> 123 -> 1.23
+    alert( Math.round(num * 100) / 100 ); // 1.23456 -> 123.456 -> 123 -> 1.23
     ```
 
 2. The method [toFixed(n)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed) rounds the number to `n` digits after the point and returns a string representation of the result.

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

@@ -528,7 +528,7 @@ The characters are compared by their numeric code. The greater code means that t
 - All lowercase letters go after uppercase letters because their codes are greater.
 - Some letters like `Ö` stand apart from the main alphabet. Here, it's code is greater than anything from `a` to `z`.
 
-### Correct comparisons
+### Correct comparisons [#correct-comparisons]
 
 The "right" algorithm to do string comparisons is more complex than it may seem, because alphabets are different for different languages.
 

1-js/06-advanced-functions/06-function-object/article.md

@@ -1,7 +1,7 @@
 
 # Function object, NFE
 
-As we already know, functions in JavaScript are values.
+As we already know, a function in JavaScript is a value.
 
 Every value in JavaScript has a type. What type is a function?
 
@@ -12,7 +12,7 @@ A good way to imagine functions is as callable "action objects". We can not only
 
 ## The "name" property
 
-Function objects contain a few useable properties.
+Function objects contain some useable properties.
 
 For instance, a function's name is accessible as the "name" property:
 
@@ -24,14 +24,14 @@ function sayHi() {
 alert(sayHi.name); // sayHi
 ```
 
-What's more funny, the name-assigning logic is smart. It also assigns the correct name to functions that are used in assignments:
+What's kind of funny, the name-assigning logic is smart. It also assigns the correct name to a function even if it's created without one, and then immediately assigned:
 
 ```js run
 let sayHi = function() {
   alert("Hi");
-}
+};
 
-alert(sayHi.name); // sayHi (works!)
+alert(sayHi.name); // sayHi (there's a name!)
 ```
 
 It also works if the assignment is done via a default value:
@@ -93,7 +93,7 @@ alert(many.length); // 2
 
 Here we can see that rest parameters are not counted.
 
-The `length` property is sometimes used for introspection in functions that operate on other functions.
+The `length` property is sometimes used for [introspection](https://en.wikipedia.org/wiki/Type_introspection) in functions that operate on other functions.
 
 For instance, in the code below the `ask` function accepts a `question` to ask and an arbitrary number of `handler` functions to call.
 
@@ -102,9 +102,9 @@ Once a user provides their answer, the function calls the handlers. We can pass
 - A zero-argument function, which is only called when the user gives a positive answer.
 - A function with arguments, which is called in either case and returns an answer.
 
-The idea is that we have a simple, no-arguments handler syntax for positive cases (most frequent variant), but are able to provide universal handlers as well.
+To call `handler` the right way, we examine the `handler.length` property.
 
-To call `handlers` the right way, we examine the `length` property:
+The idea is that we have a simple, no-arguments handler syntax for positive cases (most frequent variant), but are able to support universal handlers as well:
 
 ```js run
 function ask(question, ...handlers) {
@@ -153,7 +153,7 @@ alert( `Called ${sayHi.counter} times` ); // Called 2 times
 ```warn header="A property is not a variable"
 A property assigned to a function like `sayHi.counter = 0` does *not* define a local variable `counter` inside it. In other words, a property `counter` and a variable `let counter` are two unrelated things.
 
-We can treat a function as an object, store properties in it, but that has no effect on its execution. Variables never use function properties and vice versa. These are just parallel worlds.
+We can treat a function as an object, store properties in it, but that has no effect on its execution. Variables are not function properties and vice versa. These are just parallel worlds.
 ```
 
 Function properties can replace closures sometimes. For instance, we can rewrite the counter function example from the chapter <info:closure> to use a function property:
@@ -241,7 +241,7 @@ let sayHi = function *!*func*/!*(who) {
 sayHi("John"); // Hello, John
 ```
 
-There are two special things about the name `func`:
+There are two special things about the name `func`, that are the reasons for it:
 
 1. It allows the function to reference itself internally.
 2. It is not visible outside of the function.
@@ -282,7 +282,7 @@ let sayHi = function(who) {
 };
 ```
 
-The problem with that code is that the value of `sayHi` may change. The function may go to another variable, and the code will start to give errors:
+The problem with that code is that `sayHi` may change in the outer code. If the function gets assigned to another variable instead, the code will start to give errors:
 
 ```js run
 let sayHi = function(who) {
@@ -326,7 +326,7 @@ welcome(); // Hello, Guest (nested call works)
 
 Now it works, because the name `"func"` is function-local. It is not taken from outside (and not visible there). The specification guarantees that it will always reference the current function.
 
-The outer code still has it's variable `sayHi` or `welcome`. And `func` is an "internal function name", how the function can call itself internally.
+The outer code still has its variable `sayHi` or `welcome`. And `func` is an "internal function name", how the function can call itself internally.
 
 ```smart header="There's no such thing for Function Declaration"
 The "internal name" feature described here is only available for Function Expressions, not for Function Declarations. For Function Declarations, there is no syntax for adding an "internal" name.
@@ -340,7 +340,7 @@ Functions are objects.
 
 Here we covered their properties:
 
-- `name` -- the function name. Exists not only when given in the function definition, but also for assignments and object properties.
+- `name` -- the function name. Usually taken from the function definition, but if there's none, JavaScript tries to guess it from the context (e.g. an assignment).
 - `length` -- the number of arguments in the function definition. Rest parameters are not counted.
 
 If the function is declared as a Function Expression (not in the main code flow), and it carries the name, then it is called a Named Function Expression. The name can be used inside to reference itself, for recursive calls or such.

1-js/09-classes/03-static-properties-methods/article.md

@@ -1,9 +1,9 @@
 
 # Static properties and methods
 
-We can also assign a method to the class function, not to its `"prototype"`. Such methods are called *static*.
+We can also assign a method to the class function itself, not to its `"prototype"`. Such methods are called *static*.
 
-An example:
+In a class, they are prepended by `static` keyword, like this:
 
 ```js run
 class User {
@@ -17,7 +17,7 @@ class User {
 User.staticMethod(); // true
 ```
 
-That actually does the same as assigning it as a function property:
+That actually does the same as assigning it as a property directly:
 
 ```js run
 class User { }
@@ -29,11 +29,11 @@ User.staticMethod = function() {
 User.staticMethod(); // true
 ```
 
-The value of `this` inside `User.staticMethod()` is the class constructor `User` itself (the "object before dot" rule).
+The value of `this` in `User.staticMethod()` call is the class constructor `User` itself (the "object before dot" rule).
 
 Usually, static methods are used to implement functions that belong to the class, but not to any particular object of it.
 
-For instance, we have `Article` objects and need a function to compare them. The natural choice would be `Article.compare`, like this:
+For instance, we have `Article` objects and need a function to compare them. A natural solution would be to add `Article.compare` method, like this:
 
 ```js run
 class Article {
@@ -51,25 +51,25 @@ class Article {
 
 // usage
 let articles = [
-  new Article("Mind", new Date(2019, 1, 1)),
-  new Article("Body", new Date(2019, 0, 1)),
+  new Article("HTML", new Date(2019, 1, 1)),
+  new Article("CSS", new Date(2019, 0, 1)),
   new Article("JavaScript", new Date(2019, 11, 1))
 ];
 
 *!*
 articles.sort(Article.compare);
 */!*
 
-alert( articles[0].title ); // Body
+alert( articles[0].title ); // CSS
 ```
 
-Here `Article.compare` stands "over" the articles, as a means to compare them. It's not a method of an article, but rather of the whole class.
+Here `Article.compare` stands "above" articles, as a means to compare them. It's not a method of an article, but rather of the whole class.
 
 Another example would be a so-called "factory" method. Imagine, we need few ways to create an article:
 
 1. Create by given parameters (`title`, `date` etc).
 2. Create an empty article with today's date.
-3. ...
+3. ...or else somehow.
 
 The first way can be implemented by the constructor. And for the second one we can make a static method of the class.
 
@@ -109,7 +109,7 @@ Article.remove({id: 12345});
 
 [recent browser=Chrome]
 
-Static properties are also possible, just like regular class properties:
+Static properties are also possible, they look like regular class properties, but prepended by `static`:
 
 ```js run
 class Article {
@@ -125,7 +125,7 @@ That is the same as a direct assignment to `Article`:
 Article.publisher = "Ilya Kantor";
 ```
 
-## Inheritance of static properties and methods
+## Inheritance of static properties and methods [#statics-and-inheritance]
 
 Static properties and methods are inherited.
 
@@ -176,20 +176,24 @@ alert(Rabbit.planet); // Earth
 
 Now when we call `Rabbit.compare`, the inherited `Animal.compare` will be called.
 
-How does it work? Again, using prototypes. As you might have already guessed, extends also gives `Rabbit` the `[[Prototype]]` reference to `Animal`.
-
+How does it work? Again, using prototypes. As you might have already guessed, `extends` gives `Rabbit` the `[[Prototype]]` reference to `Animal`.
 
 ![](animal-rabbit-static.svg)
 
+So, `Rabbit extends Animal` creates two `[[Prototype]]` references:
+
+1. `Rabbit` function prototypally inherits from `Animal` function.
+2. `Rabbit.prototype` prototypally inherits from `Animal.prototype`.
+
 As a result, inheritance works both for regular and static methods.
 
-Here, let's check that:
+Here, let's check that by code:
 
 ```js run
 class Animal {}
 class Rabbit extends Animal {}
 
-// for static properties and methods
+// for statics
 alert(Rabbit.__proto__ === Animal); // true
 
 // for regular methods
@@ -200,9 +204,9 @@ alert(Rabbit.prototype.__proto__ === Animal.prototype); // true
 
 Static methods are used for the functionality that belongs to the class "as a whole". It doesn't relate to a concrete class instance.
 
-## Summary
+For example, a method for comparison `Article.compare(article1, article2)` or a factory method `Article.createTodays()`.
 
-Static methods are used for the functionality that doesn't relate to a concrete class instance, doesn't require an instance to exist, but rather belongs to the class as a whole, like `Article.compare` -- a generic method to compare two articles.
+They are labeled by the word `static` in class declaration.
 
 Static properties are used when we'd like to store class-level data, also not bound to an instance.
 
@@ -218,13 +222,13 @@ class MyClass {
 }
 ```
 
-That's technically the same as assigning to the class itself:
+Technically, static declaration is the same as assigning to the class itself:
 
 ```js
 MyClass.property = ...
 MyClass.method = ...
 ```
 
-Static properties are inherited.
+Static properties and methods are inherited.
 
-Technically, for `class B extends A` the prototype of the class `B` itself points to `A`: `B.[[Prototype]] = A`. So if a field is not found in `B`, the search continues in `A`.
+For `class B extends A` the prototype of the class `B` itself points to `A`: `B.[[Prototype]] = A`. So if a field is not found in `B`, the search continues in `A`.

1-js/10-error-handling/1-try-catch/1-finally-or-code-after/solution.md

@@ -1,8 +1,8 @@
 The difference becomes obvious when we look at the code inside a function.
 
-The behavior is different if there's a "jump out" of `try..catch`.
+The behavior is different if there's a "jump out" of `try...catch`.
 
-For instance, when there's a `return` inside `try..catch`. The `finally` clause works in case of *any* exit from `try..catch`, even via the `return` statement: right after `try..catch` is done, but before the calling code gets the control.
+For instance, when there's a `return` inside `try...catch`. The `finally` clause works in case of *any* exit from `try...catch`, even via the `return` statement: right after `try...catch` is done, but before the calling code gets the control.
 
 ```js run
 function f() {
@@ -11,7 +11,7 @@ function f() {
 *!*
     return "result";
 */!*
-  } catch (e) {
+  } catch (err) {
     /// ...
   } finally {
     alert('cleanup!');
@@ -28,11 +28,11 @@ function f() {
   try {
     alert('start');
     throw new Error("an error");
-  } catch (e) {
+  } catch (err) {
     // ...
     if("can't handle the error") {
 *!*
-      throw e;
+      throw err;
 */!*
     }
 
@@ -44,4 +44,4 @@ function f() {
 f(); // cleanup!
 ```
 
-It's `finally` that guarantees the cleanup here. If we just put the code at the end of `f`, it wouldn't run.
+It's `finally` that guarantees the cleanup here. If we just put the code at the end of `f`, it wouldn't run in these situations.

1-js/10-error-handling/1-try-catch/1-finally-or-code-after/task.md

@@ -6,25 +6,25 @@ importance: 5
 
 Compare the two code fragments.
 
-1. The first one uses `finally` to execute the code after `try..catch`:
+1. The first one uses `finally` to execute the code after `try...catch`:
 
     ```js
     try {
       work work
-    } catch (e) {
+    } catch (err) {
       handle errors
     } finally {
     *!*
       cleanup the working space
     */!*
     }
     ```
-2. The second fragment puts the cleaning right after `try..catch`:
+2. The second fragment puts the cleaning right after `try...catch`:
 
     ```js
     try {
       work work
-    } catch (e) {
+    } catch (err) {
       handle errors
     }
 
@@ -33,6 +33,6 @@ Compare the two code fragments.
     */!*
     ```
 
-We definitely need the cleanup after the work has started, doesn't matter if there was an error or not.
+We definitely need the cleanup after the work, doesn't matter if there was an error or not.
 
 Is there an advantage here in using `finally` or both code fragments are equal? If there is such an advantage, then give an example when it matters.