Merge branch 'master' of github.com:javascript-tutorial/en.javascript.info into sync-9cb33f40

Author: root

1-js/02-first-steps/03-strict-mode/article.md

@@ -53,9 +53,17 @@ For the future, when you use a browser console to test features, please note tha
 
 Sometimes, when `use strict` makes a difference, you'll get incorrect results.
 
-Even if we press `key:Shift+Enter` to input multiple lines, and put `use strict` on top, it doesn't work. That's because of how the console executes the code internally.
+You can try to press `key:Shift+Enter` to input multiple lines, and put `use strict` on top, like this:
 
-The reliable way to ensure `use strict` would be to input the code into console like this:
+```js
+'use strict'; <Shift+Enter for a newline>
+//  ...your code
+<Enter to run>
+```
+
+It works in most browsers, namely Firefox and Chrome.
+
+If it doesn't, the most reliable way to ensure `use strict` would be to input the code into console like this:
 
 ```js
 (function() {

1-js/03-code-quality/04-ninja-code/article.md

@@ -137,7 +137,7 @@ Instead, reuse existing names. Just write new values into them.
 
 In a function try to use only variables passed as parameters.
 
-That would make it really hard to identify what's exactly in the variable *now*. And also where it comes from. A person with weak intuition would have to analyze the code line-by-line and track the changes through every code branch.
+That would make it really hard to identify what's exactly in the variable *now*. And also where it comes from. The purpose is to develop the intuition and memory of a person reading the code. A person with weak intuition would have to analyze the code line-by-line and track the changes through every code branch.
 
 **An advanced variant of the approach is to covertly (!) replace the value with something alike in the middle of a loop or a function.**
 
@@ -155,7 +155,7 @@ function ninjaFunction(elem) {
 
 A fellow programmer who wants to work with `elem` in the second half of the function will be surprised... Only during the debugging, after examining the code they will find out that they're working with a clone!
 
-Seen in code regularly. Deadly effective even against an experienced ninja. 
+Seen in code regularly. Deadly effective even against an experienced ninja.
 
 ## Underscores for fun
 
@@ -169,8 +169,7 @@ A smart ninja puts underscores at one spot of code and evades them at other plac
 
 Let everyone see how magnificent your entities are! Names like `superElement`, `megaFrame` and `niceItem` will definitely enlighten a reader.
 
-Indeed, from one hand, something is written: `super..`, `mega..`, `nice..` But from the other hand -- that brings no details. A reader may decide to look for a hidden meaning and meditate for an hour or two.
-
+Indeed, from one hand, something is written: `super..`, `mega..`, `nice..` But from the other hand -- that brings no details. A reader may decide to look for a hidden meaning and meditate for an hour or two of their paid working time.
 
 
 ## Overlap outer variables
@@ -180,7 +179,7 @@ When in the light, can't see anything in the darkness.<br>
 When in the darkness, can see everything in the light.
 ```
 
-Use same names for variables inside and outside a function. As simple. No efforts required.
+Use same names for variables inside and outside a function. As simple. No efforts to invent new names.
 
 ```js
 let *!*user*/!* = authenticateUser();

1-js/06-advanced-functions/11-currying-partials/article.md

@@ -170,7 +170,7 @@ To understand the benefits we definitely need a worthy real-life example.
 
 Advanced currying allows the function to be both callable normally and partially.
 
-For instance, we have the logging function `log(date, importance, message)` that formats and outputs the information. In real projects such functions also have many other useful features like sending logs over the network:
+For instance, we have the logging function `log(date, importance, message)` that formats and outputs the information. In real projects such functions also have many other useful features like sending logs over the network, here we just use `alert`:
 
 ```js
 function log(date, importance, message) {
@@ -184,34 +184,29 @@ Let's curry it!
 log = _.curry(log);
 ```
 
-After that `log` still works the normal way:
-
-```js
-log(new Date(), "DEBUG", "some debug");
-```
-
-...But also can be called in the curried form:
+After that `log` work both the normal way and in the curried form:
 
 ```js
+log(new Date(), "DEBUG", "some debug"); // log(a,b,c)
 log(new Date())("DEBUG")("some debug"); // log(a)(b)(c)
 ```
 
-Let's get a convenience function for today's logs:
+Now we can easily make a convenience function for current logs:
 
 ```js
-// todayLog will be the partial of log with fixed first argument
-let todayLog = log(new Date());
+// currentLog will be the partial of log with fixed first argument
+let currentLog = log(new Date());
 
 // use it
-todayLog("INFO", "message"); // [HH:mm] INFO message
+currentLog("INFO", "message"); // [HH:mm] INFO message
 ```
 
-And now a convenience function for today's debug messages:
+And here's a convenience function for current debug messages:
 
 ```js
-let todayDebug = todayLog("DEBUG");
+let todayDebug = currentLog("DEBUG");
 
-todayDebug("message"); // [HH:mm] DEBUG message
+currentLog("message"); // [HH:mm] DEBUG message
 ```
 
 So:

1-js/11-async/02-promise-basics/article.md

@@ -278,7 +278,7 @@ The good thing is: a `.then` handler is guaranteed to run whether the promise ta
 
 Next, let's see more practical examples of how promises can help us to write asynchronous code.
 
-## Example: loadScript
+## Example: loadScript [#loadscript]
 
 We've got the `loadScript` function for loading a script from the previous chapter.
 

1-js/11-async/03-promise-chaining/article.md

@@ -146,7 +146,7 @@ Returning promises allows us to build chains of asynchronous actions.
 
 ## Example: loadScript
 
-Let's use this feature with `loadScript` to load scripts one by one, in sequence:
+Let's use this feature with the promisified `loadScript`, defined in the [previous chapter](/promise-basics#loadscript), to load scripts one by one, in sequence:
 
 ```js run
 loadScript("/article/promise-chaining/one.js")
@@ -305,7 +305,7 @@ fetch('/article/promise-chaining/user.json')
   });
 ```
 
-The code works, see comments about the details, but it should be quite self-descriptive. Although, there's a potential problem in it, a typical error of those who begin to use promises.
+The code works, see comments about the details. Although, there's a potential problem in it, a typical error of those who begin to use promises.
 
 Look at the line `(*)`: how can we do something *after* the avatar has finished showing and gets removed? For instance, we'd like to show a form for editing that user or something else. As of now, there's no way.
 

1-js/11-async/07-microtask-queue/article.md

@@ -124,7 +124,6 @@ Naturally, `promise` shows up first, because `setTimeout` macrotask awaits in th
 
 As a logical consequence, macrotasks are handled only when promises give the engine a "free time". So if we have a chain of promise handlers that don't wait for anything, execute right one after another, then a `setTimeout` (or a user action handler) can never run in-between them.
 
-
 ## Unhandled rejection
 
 Remember "unhandled rejection" event from the chapter <info:promise-error-handling>?

1-js/12-generators-iterators/2-async-iterators-generators/article.md

@@ -3,13 +3,13 @@
 
 Asynchronous iterators allow to iterate over data that comes asynchronously, on-demand.
 
-For instance, when we download something chunk-by-chunk, or just expect events to come asynchronously and would like to iterate over them -- async iterators and generators may come in handy. Let's see a simple example first, to grasp the syntax, and then review a real-life use case.
+For instance, when we download something chunk-by-chunk, and expect data fragments to come asynchronously and would like to iterate over them -- async iterators and generators may come in handy. Let's see a simple example first, to grasp the syntax, and then review a real-life use case.
 
 ## Async iterators
 
-Asynchronous iterators are totally similar to regular iterators, with a few syntactic differences.
+Asynchronous iterators are similar to regular iterators, with a few syntactic differences.
 
-"Regular" iterable object from the chapter <info:iterable> look like this:
+"Regular" iterable object, as described in the chapter <info:iterable>, look like this:
 
 ```js run
 let range = {
@@ -101,7 +101,7 @@ let range = {
 })()
 ```
 
-As we can see, the components are similar to regular iterators:
+As we can see, the structure is similar to regular iterators:
 
 1. To make an object asynchronously iterable, it must have a method `Symbol.asyncIterator` `(1)`.
 2. It must return the object with `next()` method returning a promise `(2)`.
@@ -117,22 +117,22 @@ Here's a small cheatsheet:
 | to loop, use                          | `for..of`         | `for await..of` |
 
 
-````warn header="The spread operator doesn't work asynchronously"
+````warn header="The spread operator ...  doesn't work asynchronously"
 Features that require regular, synchronous iterators, don't work with asynchronous ones.
 
 For instance, a spread operator won't work:
 ```js
 alert( [...range] ); // Error, no Symbol.iterator
 ```
 
-That's natural, as it expects to find `Symbol.iterator`, same as `for..of` without `await`.
+That's natural, as it expects to find `Symbol.iterator`, same as `for..of` without `await`. Not `Symbol.asyncIterator`.
 ````
 
 ## Async generators
 
-JavaScript also provides generators, that are also iterable.
+As we already know, JavaScript also supprots generators, and they are iterable.
 
-Let's recall a sequence generator from the chapter [](info:generators). It generates a sequence of values from `start` to `end` (could be anything else):
+Let's recall a sequence generator from the chapter [](info:generators). It generates a sequence of values from `start` to `end`:
 
 ```js run
 function* generateSequence(start, end) {
@@ -147,7 +147,7 @@ for(let value of generateSequence(1, 5)) {
 ```
 
 
-Normally, we can't use `await` in generators. All values must come synchronously: there's no place for delay in `for..of`.
+Normally, we can't use `await` in generators. All values must come synchronously: there's no place for delay in `for..of`, it's a synchronous construct.
 
 But what if we need to use `await` in the generator body? To perform network requests, for instance.
 
@@ -184,15 +184,15 @@ It's indeed very simple. We add the `async` keyword, and the generator now can u
 
 Technically, another the difference of an async generator is that its `generator.next()` method is now asynchronous also, it returns promises.
 
-Instead of `result = generator.next()` for a regular, non-async generator, values can be obtained like this:
+In a regular generator we'd use `result = generator.next()` to get values. In an async generator, we should add `await`, like this:
 
 ```js
 result = await generator.next(); // result = {value: ..., done: true/false}
 ```
 
 ## Iterables via async generators
 
-When we'd like to make an object iterable, we should add `Symbol.iterator` to it.
+As we already know, to make an object iterable, we should add `Symbol.iterator` to it.
 
 ```js
 let range = {
@@ -270,7 +270,7 @@ The pattern is very common, it's not about users, but just about anything. For i
 - It responds with a JSON of 30 commits, and also provides a link to the next page in the `Link` header.
 - Then we can use that link for the next request, to get more commits, and so on.
 
-What we'd like to have is an iterable source of commits, so that we could use it like this:
+What we'd like to have is a simpler API: an iterable object with commits, so that we could go over them like this:
 
 ```js
 let repo = 'javascript-tutorial/en.javascript.info'; // GitHub repository to get commits from
@@ -332,7 +332,7 @@ An example of use (shows commit authors in console):
 })();
 ```
 
-That's just what we wanted. The internal pagination mechanics is invisible from the outside. For us it's just an async generator that returns commits.
+That's just what we wanted. The internal mechanics of paginated requests is invisible from the outside. For us it's just an async generator that returns commits.
 
 ## Summary
 
@@ -356,6 +356,6 @@ Syntax differences between async and regular generators:
 
 In web-development we often meet streams of data, when it flows chunk-by-chunk. For instance, downloading or uploading a big file.
 
-We could use async generators to process such data, but there's also another API called Streams, that may be more convenient, as it provides special interfaces to transform the data and to pass it from one stream to another (e.g. download from one place and immediately send elsewhere). But they are also more complex.
+We can use async generators to process such data, but it's worth to mention that there's also another API called Streams, that provides special interfaces to transform the data and to pass it from one stream to another (e.g. download from one place and immediately send elsewhere). 
 
 Streams API not a part of JavaScript language standard. Streams and async generators complement each other, both are great ways to handle async data flows.

2-ui/1-document/08-styles-and-classes/article.md

@@ -66,10 +66,10 @@ So we can operate both on the full class string using `className` or on individu
 Methods of `classList`:
 
 - `elem.classList.add/remove("class")` -- adds/removes the class.
-- `elem.classList.toggle("class")` -- if the class exists, then removes it, otherwise adds it.
+- `elem.classList.toggle("class")` -- adds the class if it doesn't exist, otherwise removes it.
 - `elem.classList.contains("class")` -- returns `true/false`, checks for the given class.
 
-Besides that, `classList` is iterable, so we can list all classes like this:
+Besides, `classList` is iterable, so we can list all classes with `for..of`, like this:
 
 ```html run
 <body class="main page">
@@ -147,7 +147,7 @@ To set the full style as a string, there's a special property `style.cssText`:
 </script>
 ```
 
-We rarely use it, because such assignment removes all existing styles: it does not add, but replaces them. May occasionally delete something needed. But still can be done for new elements when we know we won't delete something important.
+This property is rarely used, because such assignment removes all existing styles: it does not add, but replaces them. May occasionally delete something needed. But we can safely use it for new elements, when we know we won't delete an existing style.
 
 The same can be accomplished by setting an attribute: `div.setAttribute('style', 'color: red...')`.
 ````

2-ui/2-events/03-event-delegation/4-behavior-tooltip/task.md

@@ -18,7 +18,7 @@ Should work like this:
 
 [iframe src="solution" height=200 border=1]
 
-In this task we assume that all elements with `data-tooltip` have only text inside. No nested tags.
+In this task we assume that all elements with `data-tooltip` have only text inside. No nested tags (yet).
 
 Details:
 
@@ -33,4 +33,4 @@ Please use event delegation: set up two handlers on `document` to track all "ove
 
 After the behavior is implemented, even people unfamiliar with JavaScript can add annotated elements.
 
-P.S. To keep things natural and simple: only one tooltip may show up at a time.
+P.S. Only one tooltip may show up at a time.

2-ui/2-events/03-event-delegation/article.md

@@ -182,7 +182,7 @@ The pattern has two parts:
 
 ### Counter
 
-For instance, here the attribute `data-counter` adds a behavior: "increase on click" to buttons:
+For instance, here the attribute `data-counter` adds a behavior: "increase value on click" to buttons:
 
 ```html run autorun height=60
 Counter: <input type="button" value="1" data-counter>