Merge pull request #10785 from wizardofhogwarts/patch-6

docs: improve documentation of examples

examples/top-level-await/README.md

@@ -1,5 +1,5 @@
-Let's use `await` at top level in a module `db-connection.js`.
-This makes sense since the connection to the DB need to established before the module is usable.
+Let's use `await` at the top level in a module `db-connection.js`.
+This makes sense since the connection to the DB needs to be established before the module is usable.
 
 # db-connection.js
 
@@ -25,15 +25,15 @@ export const close = () => {
 But `db-connection.js` is no longer a normal module now.
 It's an **async module** now.
 Async modules have a different evaluation semantics.
-While normal modules evaluate in a synchronous way, async modules evaluate in an asynchronous way.
+While normal modules evaluate synchronously way, async modules evaluate asynchronously.
 
-Async modules can't imported with a normal `import`.
+Async modules can't be imported with a normal `import`.
 They need to be imported with `import await`.
 
 The main reason for this is to make the using module aware of the different evaluation semantics.
 
 Using `import await` in a module also makes the module an async module.
-You can see it as form of top-level-await, but it's a bit different because imports hoist, so does `import await`.
+You can see it as a form of top-level-await, but it's a bit different because imports hoist, so does `import await`.
 All `import`s and `import await`s hoist and are evaluated in parallel.
 
 `import await` doesn't affect tree shaking negatively.
@@ -56,7 +56,7 @@ Now it looks like that this pattern will continue and will infect all using modu
 Yes, this is kind of true and makes sense.
 All these modules have their evaluation semantics changed to be async.
 
-But you as developer don't want this.
+But you as a developer don't want this.
 You want to break the chain at a point in your module graph where it makes sense.
 Luckily there is a nice way to break the chain.
 
@@ -113,12 +113,12 @@ import { CreateUserAction } from "./Actions.js";
 ```
 
 Note that you may `import await` from a normal module too.
-This is legal, but mostly unneeded.
-`import await` may also been seen by developers as hint that this dependency does some async actions and may delay evaluation.
+This is legal, but mostly not required.
+`import await` may also be seen by developers as a hint that this dependency does some async actions and may delay evaluation.
 
-As guideline you should prevent your application entry point to become an async module when compiling for web targets.
+As a guideline, you should prevent your application entry point to become an async module when compiling for web targets.
 Doing async actions at application bootstrap will delay your application startup and may be negative for UX.
-Use `import()` to do async action on demand or in background and use spinners or other indicators to inform the user about background actions.
+Use `import()` to do async action on-demand or in the background and use spinners or other indicators to inform the user about background actions.
 
 When compiling for other targets like node.js, electron or WebWorkers, it may be fine that your entry point becomes an async module.
 

examples/top-level-await/template.md

@@ -1,5 +1,5 @@
-Let's use `await` at top level in a module `db-connection.js`.
-This makes sense since the connection to the DB need to established before the module is usable.
+Let's use `await` at the top level in a module `db-connection.js`.
+This makes sense since the connection to the DB needs to be established before the module is usable.
 
 # db-connection.js
 
@@ -10,15 +10,15 @@ _{{db-connection.js}}_
 But `db-connection.js` is no longer a normal module now.
 It's an **async module** now.
 Async modules have a different evaluation semantics.
-While normal modules evaluate in a synchronous way, async modules evaluate in an asynchronous way.
+While normal modules evaluate synchronously, async modules evaluate asynchronously.
 
-Async modules can't imported with a normal `import`.
+Async modules can't be imported with a normal `import`.
 They need to be imported with `import await`.
 
 The main reason for this is to make the using module aware of the different evaluation semantics.
 
 Using `import await` in a module also makes the module an async module.
-You can see it as form of top-level-await, but it's a bit different because imports hoist, so does `import await`.
+You can see it as a form of top-level-await, but it's a bit different because imports hoist, so does `import await`.
 All `import`s and `import await`s hoist and are evaluated in parallel.
 
 `import await` doesn't affect tree shaking negatively.
@@ -35,7 +35,7 @@ Now it looks like that this pattern will continue and will infect all using modu
 Yes, this is kind of true and makes sense.
 All these modules have their evaluation semantics changed to be async.
 
-But you as developer don't want this.
+But you as a developer don't want this.
 You want to break the chain at a point in your module graph where it makes sense.
 Luckily there is a nice way to break the chain.
 
@@ -62,12 +62,12 @@ _{{example.js}}_
 ```
 
 Note that you may `import await` from a normal module too.
-This is legal, but mostly unneeded.
-`import await` may also been seen by developers as hint that this dependency does some async actions and may delay evaluation.
+This is legal, but mostly not required.
+`import await` may also be seen by developers as a hint that this dependency does some async actions and may delay evaluation.
 
-As guideline you should prevent your application entry point to become an async module when compiling for web targets.
+As a guideline, you should prevent your application entry point to become an async module when compiling for web targets.
 Doing async actions at application bootstrap will delay your application startup and may be negative for UX.
-Use `import()` to do async action on demand or in background and use spinners or other indicators to inform the user about background actions.
+Use `import()` to do async action on-demand or in the background and use spinners or other indicators to inform the user about background actions.
 
 When compiling for other targets like node.js, electron or WebWorkers, it may be fine that your entry point becomes an async module.
 

examples/wasm-simple/README.md

@@ -1,7 +1,7 @@
-This very simple example shows usage of WebAssembly.
+This is a simple example that shows the usage of WebAssembly.
 
 WebAssembly modules can be imported like other async modules with `import await` or `import()`.
-They are downloaded and instantiated in a streaming way when importing.
+When importing, they are downloaded and instantiated in a streaming way.
 
 # example.js
 

examples/wasm-simple/template.md

@@ -1,7 +1,7 @@
-This very simple example shows usage of WebAssembly.
+This is a simple example that shows the usage of WebAssembly.
 
 WebAssembly modules can be imported like other async modules with `import await` or `import()`.
-They are downloaded and instantiated in a streaming way when importing.
+When importing, they are downloaded and instantiated in a streaming way.
 
 # example.js