add async-do-expressions docs (#2486)

docs/parser.md

@@ -184,6 +184,7 @@ require("@babel/parser").parse("code", {
   <summary>History</summary>
 | Version | Changes |
 | --- | --- |
+| `v7.14.0` | Added `asyncDoExpressions` |
 | `v7.13.0` | Added `moduleBlocks` |
 | `v7.12.0` | Added `classStaticBlock`, `moduleStringNames` |
 | `v7.11.0` | Added `decimal` |
@@ -196,6 +197,7 @@ require("@babel/parser").parse("code", {
 
 | Name                                                                                            | Code Example                                             |
 | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `asyncDoExpressions` ([proposal](https://github.com/tc39/proposal-async-do-expressions))        | `async do { await requestAPI().json() }`                 |
 | `classProperties` ([proposal](https://github.com/tc39/proposal-class-public-fields))            | `class A { b = 1; }`                                     |
 | `classPrivateProperties` ([proposal](https://github.com/tc39/proposal-private-fields))          | `class A { #b = 1; }`                                    |
 | `classPrivateMethods` ([proposal](https://github.com/tc39/proposal-private-methods))            | `class A { #c() {} }`                                    |

docs/plugin-proposal-async-do-expressions.md

@@ -0,0 +1,90 @@
+---
+id: babel-plugin-proposal-async-do-expressions
+title: @babel/plugin-proposal-async-do-expressions
+sidebar_label: async-do-expressions
+---
+
+> The `async do { .. }` expression executes a block (with one or many statements in it) in an _asynchronous_ context, and the final statement completion value inside the block becomes the completion value of the _asynchronous_ code.
+
+## Example
+
+Issuing HTTP request in parallel
+
+```js
+Promise.all([
+  async do {
+    const result = await fetch('https://example.com/A');
+    await result.json()
+  },
+  async do {
+    const result = await fetch('https://example.org/B');
+    await result.json()
+  },
+]).then(([a, b]) => {
+  console.log("example.com/A", a);
+  console.log("example.org/B", b);
+})
+```
+
+will be transformed to
+
+```js
+Promise.all([
+  (async () {
+    const result = await fetch('https://example.com/A');
+    return await result.json()
+  })(),
+  (async () {
+    const result = await fetch('https://example.org/B');
+    return await result.json()
+  })(),
+]).then(([a, b]) => {
+  console.log("example.com/A", a);
+  console.log("example.org/B", b);
+})
+```
+
+## Installation
+
+```sh
+npm install --save-dev @babel/plugin-proposal-async-do-expressions
+```
+
+## Usage
+
+### With a configuration file (Recommended)
+
+```json
+{
+  "plugins": ["@babel/plugin-proposal-async-do-expressions"]
+}
+```
+
+Note: This plugin transpiles `async do {}` to ES2017 Async arrow function `async () => {}`. If you target to an older engine, i.e. Node.js 6 or IE 11, please also add [`@babel/plugin-transform-async-to-generator`](plugin-transform-async-to-generator.md):
+
+```
+{
+  "plugins": [
+    "@babel/plugin-proposal-async-do-expressions",
+    "@babel/plugin-transform-async-to-generator"
+  ]
+}
+```
+
+### Via CLI
+
+```sh
+babel --plugins @babel/plugin-proposal-async-do-expressions script.js
+```
+
+### Via Node API
+
+```javascript
+require("@babel/core").transformSync("code", {
+  plugins: ["@babel/plugin-proposal-async-do-expressions"],
+});
+```
+
+## References
+
+- [Proposal](https://github.com/tc39/proposal-async-do-expressions)

docs/plugin-syntax-async-do-expressions.md

@@ -0,0 +1,39 @@
+---
+id: babel-plugin-syntax-async-do-expressions
+title: @babel/plugin-syntax-async-do-expressions
+sidebar_label: syntax-async-do-expressions
+---
+
+> #### Syntax only
+>
+> It's unlikely you want to use this plugin directly as it only enables Babel to parse this syntax. Instead, use [plugin-proposal-async-do-expressions](plugin-proposal-async-do-expressions.md) to _both_ parse and transform this syntax.
+
+## Installation
+
+```sh
+npm install --save-dev @babel/plugin-syntax-async-do-expressions
+```
+
+## Usage
+
+### With a configuration file (Recommended)
+
+```json
+{
+  "plugins": ["@babel/plugin-syntax-async-do-expressions"]
+}
+```
+
+### Via CLI
+
+```sh
+babel --plugins @babel/plugin-syntax-async-do-expressions script.js
+```
+
+### Via Node API
+
+```javascript
+require("@babel/core").transformSync("code", {
+  plugins: ["@babel/plugin-syntax-async-do-expressions"],
+});
+```

website/sidebars.json

@@ -51,6 +51,7 @@
       "babel-plugin-transform-modules-umd"
     ],
     "TC39 Proposals": [
+      "babel-plugin-proposal-async-do-expressions",
       "babel-plugin-proposal-class-properties",
       "babel-plugin-proposal-class-static-block",
       "babel-plugin-proposal-decorators",